Step 3 · First Contribution

Goal

Make a real, reviewed, merged change to the codebase — following the project's conventions end-to-end, from branch to deployment.

Instructions

You are in workflow step 3 of the onboarding-cycle. You understand the codebase. Your job is to make a real contribution and complete the full development cycle for the first time on this project.

Tasks to Perform

1. Pick a Starter Task

Good first tasks:

  • A small bug fix with a clear reproduction
  • A missing test for an existing feature
  • A documentation improvement
  • A small, isolated feature with clear acceptance criteria

Avoid for a first contribution:

  • Refactoring a large module
  • Any change that touches the authentication or payment path
  • A task with unclear requirements

Look in TODO.md for - [ ] items tagged for newcomers, or ask a teammate.

2. Create a Branch

# Pull latest main
git checkout main
git pull --rebase origin main

# Create a branch following the project's naming convention
# Check git log for the convention already in use:
git log --oneline -10

# Common conventions:
git checkout -b feat/add-address-validation
git checkout -b fix/order-status-typo
git checkout -b chore/update-readme-setup
# or ticket-number based:
git checkout -b feature/PROJ-123-add-address-validation

3. Read Before You Write

# Read every file you will touch — completely
# Read every file that calls into the files you will touch

# Find callers of a function/class you will modify:
grep -rn "functionName\|ClassName" \
  --include="*.{php,js,ts,py,rb}" . \
  | grep -v node_modules | grep -v vendor | grep -v ".git"

# Read the tests for the code you are changing
find . -name "*.test.*" -o -name "*_spec.*" \
  | xargs grep -l "functionName\|ClassName" 2>/dev/null

4. Write or Update Tests First

Before changing the implementation:

# Write a failing test that describes the expected behaviour
# (or update existing tests to cover the new case)

# Run the test to confirm it fails for the right reason
npm test -- --testNamePattern="the scenario you're testing"
php artisan test --filter=TestClassName::testMethodName
pytest tests/test_module.py::test_function_name -v

If there are no tests for the code you are changing, write them first — even for a bug fix.

5. Make the Change

Keep it small and focused:

  • Make one logical change per commit
  • Do not fix unrelated things in the same PR ("while I was in here...")
  • Do not reformat code unrelated to your change (creates noisy diffs)
  • Match the style of the surrounding code

6. Verify Locally

# Run tests
npm test
php artisan test
pytest

# Run linter
npm run lint
./vendor/bin/phpcs
ruff check .

# Run type checker
npx tsc --noEmit
./vendor/bin/phpstan analyse

# Smoke test the application manually
# Navigate to / use the feature you changed

All of these must pass before pushing.

7. Commit and Push

# Stage only the files you intended to change
git add -p   # interactive staging — review each hunk

# Commit with a clear, conventional message
# Check git log to see the format already in use
git commit -m "feat: add postcode validation to customer addresses"
# or
git commit -m "fix: correct order status transition from pending to cancelled"

# Push and set upstream
git push -u origin feat/add-address-validation

8. Open a Pull Request

# Open with GitHub CLI
gh pr create --title "feat: add postcode validation to customer addresses" \
  --body "## What\nAdds server-side postcode format validation.\n\n## Why\nInvalid postcodes were being stored, causing failed deliveries.\n\n## How\nAdded regex check in AddressService::validate(). Tests added."

# Or open in browser via GitHub/GitLab UI

PR description must include:

  • What was changed
  • Why it was needed
  • How it was implemented
  • How to test it manually

9. Respond to Review Feedback

# Make requested changes — do not argue over style unless it contradicts documented conventions
# Push additional commits (do not force-push during review unless the team does that)
git add -p
git commit -m "fix: address reviewer comment on error message wording"
git push

10. After Merge

# Clean up your local branch
git checkout main
git pull --rebase origin main
git branch -d feat/add-address-validation

# Update TODO.md:
# - [x] First contribution merged _(ref: workflows/onboarding-cycle/03-first-contribution.md)_

Exit Criteria

  • [ ] Branch created following project conventions
  • [ ] Tests written or updated before the implementation changed
  • [ ] All tests pass locally
  • [ ] Linter and type checker pass
  • [ ] Change reviewed and feedback addressed
  • [ ] PR merged to main
  • [ ] Local branch cleaned up

← Return to Step 1 · Environment Setup if setting up a new machine.

→ Continue with AutoDev for autonomous task execution on this project.