Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
74 lines (48 loc) · 3.39 KB

CONTRIBUTING.md

File metadata and controls

74 lines (48 loc) · 3.39 KB
Raw

Contributing to StackWarden

StackWarden uses Trunk Based Development. main is the only long-lived branch and must remain releasable.

Start a change

Update main, then create one short-lived branch for one coherent change:

git switch main
git pull --ff-only
git switch -c feat/short-kebab-description

Allowed branch prefixes are feat, fix, refactor, perf, test, docs, build, ci, chore, and revert. An issue number is optional: fix/123-null-output.

Do not create develop, staging, release/*, or other long-lived integration branches. Keep branches under two working days when possible. Split larger work behind backward-compatible seams or disabled feature flags.

Commit convention

Every commit and PR title follows Conventional Commits:

type(scope): lowercase description

Examples:

feat(cli): add repository policy checks
fix(config): handle an empty workspace list
docs: explain local installation
feat!: remove deprecated JSON fields

Subjects are limited to 100 characters. Allowed types match the branch prefixes above. Use ! for a breaking change and explain it in the commit body with BREAKING CHANGE:.

Commit type determines the release impact. feat creates a minor release; fix and perf create a patch release. Before 1.0, a breaking change creates a minor release and must still use ! plus a BREAKING CHANGE: footer. Internal docs, test, build, ci, refactor, and chore changes do not trigger a release by default. See the release process for the full versioning, changelog, release, and rollback convention.

Local guardrails

Install the tracked hooks once per clone:

bun run hooks:install

The commit-msg hook validates commit messages. The pre-push hook validates the current branch name. GitHub Actions repeats both checks, validates every commit and the PR title, and runs the test suite, so local hooks are a fast feedback mechanism rather than the only control.

GitHub Actions workflows are audited by zizmor on every pull request and every push to main. The check uses the pedantic persona and blocks findings. To run the same pinned version locally with uv:

uvx --from zizmor==1.28.0 zizmor --persona=pedantic .github/workflows

Integrate into the trunk

  1. Rebase or update from main before review when the branch is stale.
  2. Open a small PR with a Conventional Commit title.
  3. Merge only when required checks pass.
  4. Squash merge and delete the topic branch.
  5. Release Please derives the changelog and versions from the squash commit on main.

Prefer several independently releasable PRs over one long-running branch. If a change cannot be safely exposed yet, merge dormant code behind a feature flag rather than maintaining a parallel integration branch.

Prepare a release

Release Please maintains the release PR from commits already merged into main. Do not create release branches, version commits, tags, or changelog sections manually. Review the proposed version and public changelog, then run:

bun run release:check

Merging the green release PR creates the immutable tag and GitHub Release. The package is not yet published to npm; adding npm publication requires the separate trusted-publishing readiness work described in the release process.