docs: simplify local development setup for junior contributors#2643
Open
mroderick wants to merge 1 commit into
Open
docs: simplify local development setup for junior contributors#2643mroderick wants to merge 1 commit into
mroderick wants to merge 1 commit into
Conversation
Make native installation the officially recommended path for local development. Docker is moved to a secondary, not-recommended section. Changes: - Rewrite README.md with native installation as the quick-start path - Add docs/development-setup.md: comprehensive, junior-friendly guide covering macOS and Linux, with troubleshooting for common issues - Add lib/tasks/setup.rake: rake setup:check command that inspects the environment and reports exactly what is missing or misconfigured - Add docs/coding-agent-setup-skill.md: skill file for AI coding agents (Codex, Claude, Pi, etc.) to help contributors diagnose setup issues - Add make check target that delegates to rake setup:check - Update db/seeds.rb to reference the new docs path - Remove native-installation-instructions.md (content merged into the new guide) The setup:check task verifies: - Ruby version, Bundler, mise, PostgreSQL, ImageMagick - GitHub OAuth credentials in mise.local.toml - Bundle dependencies, database connection, migrations, test database
mroderick
force-pushed
the
feature/simplify-dev-setup
branch
from
96dc037 to
21fcc14
Compare
Collaborator
Author
|
Hey @KimberleyCook, I've tagged you for review on this PR to make the local setup easier. Could you take it for a spin, and see if it is easy to follow? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes native installation the officially recommended path for local development. The existing Docker setup is moved to a secondary, not-recommended section.
Why
Changes
docs/development-setup.md— comprehensive, junior-friendly guide covering macOS and Linux with step-by-step instructions, explanations of what each tool does, and troubleshooting for common issueslib/tasks/setup.rake—bundle exec rake setup:checkinspects the environment and reports exactly what is missing (Ruby, PostgreSQL, ImageMagick, GitHub credentials, bundle, database state, etc.)docs/coding-agent-setup-skill.md— a skill file for AI coding agents (Codex, Claude, Pi, OpenCode, etc.) to help contributors diagnose setup issues usingrake setup:checkmake checktarget that delegates torake setup:checkdb/seeds.rb— reference the new docs path when ImageMagick is missingnative-installation-instructions.md— content merged into the new guideHow to test
bundle exec rake setup:checkon a working machine → should report all greenmise.local.toml→ should report GitHub OAuth error with specific fixbundle exec rspec→ all tests passNotes
rake setup:check(also accessible viamake check)