Skip to content

developing-a-feature.md

Latest commit

 

History

History
197 lines (123 loc) · 4.54 KB

developing-a-feature.md

File metadata and controls

197 lines (123 loc) · 4.54 KB

Develop a Feature

Ship a feature end-to-end: branch, code, test, changeset, PR, and merge.

Prerequisites

Steps

1. Create a branch

Start from an up-to-date main branch:

git checkout main
git pull origin main
git checkout -b feat/my-feature

Use Conventional Commits-style branch naming: feat/, fix/, docs/, refactor/, chore/, etc.

2. Make changes

Follow the coding standards:

  • const only -- no let, no mutation
  • No classes, loops, or throw
  • Return Result tuples instead of exceptions
  • Use command() factory for CLI commands
  • Prefer pure functions, composition, and es-toolkit utilities

See the TypeScript standards and error handling standards for details.

3. Run checks frequently

Run the CI check suite as you work to catch issues early:

pnpm lint && pnpm format && pnpm typecheck

Auto-fix formatting and lint issues:

pnpm format:fix && pnpm lint:fix

4. Write tests

Add or update tests for changed code:

pnpm test

5. Commit

Use Conventional Commits format:

git commit -m "feat(packages/core): add parallel script execution"

Format: type(scope): description -- see Commit Standards for types, scopes, and examples.

Lefthook runs git hooks automatically:

Hook What it does
commit-msg Validates Conventional Commits format via commitlint
pre-commit Syncs package metadata and formats staged files with OXFmt
pre-push Runs OXLint and typecheck

6. Add a changeset

If the change affects published packages (@kidd-cli/core, @kidd-cli/*), create a changeset:

pnpm changeset

Follow the prompts to select the package, semver bump type (patch, minor, major), and write a summary. Commit the generated .changeset/*.md file with your other changes.

When to add a changeset:

  • New features, bug fixes, or breaking changes to @kidd-cli/core or @kidd-cli/* packages

When to skip:

  • Docs-only changes, CI updates, internal tooling, contributing docs

Check pending changesets:

pnpm changeset status

7. Push and open a PR

git push -u origin feat/my-feature

Open a PR against main. Use the same type(scope): description format for the PR title and include these sections in the description:

## Summary

Brief description of changes (2-3 sentences).

## Changes

- Bullet list of specific changes

## Testing

1. Step-by-step testing instructions
2. Expected behavior

## Related Issues

Closes #123

See Pull Request Standards for the full review and merge process.

CI runs: lint, format, typecheck, test.

8. Address review feedback

Respond to review comments within 24 hours. Make fixup commits and push:

git commit -m "fix(packages/core): address review feedback"
git push

9. Merge

After approval and green CI, use Squash and Merge. The Changesets bot handles versioning and npm publishing on merge to main.

Verification

Before requesting review, confirm:

  1. pnpm lint && pnpm format && pnpm typecheck && pnpm test all pass
  2. PR title follows type(scope): description format
  3. Changeset included if the change affects published packages

Troubleshooting

Pre-push hook fails

Issue: git push is blocked by lint or typecheck errors.

Fix:

pnpm lint:fix && pnpm format:fix

Fix any remaining typecheck errors, then re-push.

Changeset confusion

Issue: Unsure whether a changeset is needed or what state it is in.

Fix:

pnpm changeset status

This shows all pending changesets and which packages they affect.

Merge conflicts

Issue: PR cannot be merged due to conflicts with main.

Fix:

git fetch origin
git rebase origin/main
# Resolve conflicts
git push --force-with-lease

References