Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (66 loc) · 3.82 KB

CONTRIBUTING.md

File metadata and controls

94 lines (66 loc) · 3.82 KB
Raw

Contributing

Contribution workflow

The short version of how a change moves through this repo:

  1. Start from an issue. File one with the template that fits the work (epic, story, bug, technical-task, spike, or chore). The create-issue skill walks you through checking for duplicates, choosing a template, wording it for its audience, reviewing it, labeling it, and filing it. Every template opens with an "Issue readiness state" checklist that tracks the issue's lifecycle: reviewed by a human engineer, refinement complete, all open questions answered, post-refinement changes reviewed by a human, and ready for work. Tick the boxes as the issue advances; the refine-issue skill manages the middle three and requires the initial human review (at least one human comment on the issue) before it will run.
  2. Branch. Use the naming shape in Branching below.
  3. Make your changes. Keep commits terse and explain why, not what. Wire up the commit template (see Commit message template).
  4. Review, then open a draft PR. Run the review-draft skill on the PR description, then open the PR as a draft and fill in the template (see Opening pull requests). The create-pr skill walks you through branch naming, the review, and opening the PR.
  5. Mark ready. Move the PR out of draft once it is self-reviewed and CI passes.

Run review-draft before any durable artifact goes up: an issue, a PR description, or a commit message set. It checks quality, template adherence, voice, punctuation, and house style. The rest of this document covers each step in detail.

Local setup

Python

Requires Python 3.13.

pip install -r scripts/requirements.txt pytest

Commit message template

This repo ships a .gitmessage file that scaffolds commit messages with the expected format and a few guiding comments. Wire it up once per clone:

git config commit.template .gitmessage

After this, git commit (without -m) will open your editor pre-populated with the template. The comment lines (#) are stripped from the final message.

Branching

Use the team's standard branch shape:

<your-github-username>/<issue-number>-<short-kebab-description>

Example: jeffhorn/42-add-github-templates

If the branch lives in a different repo than the originating issue, prefix the branch description with the originating project:

jeffhorn/oscer-42-short-description

Opening pull requests

Open all pull requests as drafts initially. Mark ready for review when the work is complete and self-reviewed.

Formatting issue and PR bodies

GitHub renders issue descriptions, PR descriptions, and comments as GitHub-Flavored Markdown, and in that context it treats a single newline inside a paragraph as a line break (unlike a .md file rendered on github.com, where single newlines collapse into a space). So a body that was hard-wrapped at 72 or 80 columns renders as ragged, broken lines.

Write one line per paragraph and let it soft-wrap. Separate paragraphs with a blank line. Lists, tables, and fenced code blocks keep their own line structure and are unaffected. This is the opposite of a commit message body, which is plain text and should wrap at 72 columns (see the commit template). The distinction is by artifact: wrap commit bodies, do not wrap issue or PR bodies.

Running the pipeline

python -m scripts.lint_manifest   # validate sources.md
python -m scripts.lint_docs       # validate doc frontmatter
python -m scripts.build_graph     # write docs/INDEX.md and docs/graph.json

Run these in order before pushing. CI runs them on every relevant change. If build_graph produces a diff in docs/INDEX.md or docs/graph.json, commit the regenerated files or CI will fail.

Tests

python -m pytest -v