Contributing to git-byline
Contributions are welcome. Keep changes focused, test public behavior, and protect local repository data.
Prerequisites
- Go 1.24 or newer.
- Git 2.31 or newer.
- PromptScript CLI 1.26.0.
- GoReleaser 2.18.1 when release configuration changes.
- Syft on
PATHwhen building release snapshots.
Setup
git clone https://github.com/comarch/git-byline.git
cd git-byline
go test ./...
go build ./...
Tests create isolated temporary repositories. They must not use your working repository, home configuration, credentials, or live services.
Validation
Run narrow package tests while working:
go test ./internal/engine
go test ./internal/provenance
Before opening a pull request, run:
go run ./tools/validate
Installer changes also require shell syntax checks, PowerShell parser validation, and isolated checksum-failure and platform-selection tests.
Do not bypass a failing stage, lower coverage, weaken a fixture, or skip a required check to get a green result. See docs/VALIDATION.md.
Code rules
- Pure Go. CGo is forbidden.
- Production code must not import network packages; network access happens
only through the curl subprocess in
internal/runner. os/execis allowed only ininternal/gitcmdandinternal/runner.- Validate paths and untrusted hook input at the boundary.
- Wrap errors with context using
fmt.Errorfand%w. - Keep the attribution engine independent from Git, files, JSON, clocks, and process state.
- Keep comments short and in English.
- Use ASCII hyphens, not em dash or en dash characters.
- Add no dependency without necessity, license, source, binary size, and security justification in the pull request.
Engine and store work uses table-driven tests. Attribution behavior needs property, golden, or integration coverage. Hook changes need isolated configuration scenarios. Every bug fix includes a minimal regression test.
Fixtures must be minimal, deterministic, synthetic, or redacted. Never commit raw agent captures, transcripts, private repository paths, tokens, complete environment dumps, or production data.
Generated files
Native instruction, agent, workflow, and hook files under AGENTS.md,
CLAUDE.md, GEMINI.md, .claude/, .codex/, .cursor/, .factory/,
.gemini/, .github/agents/, .github/hooks/, .grok/, .opencode/,
.promptscript/generated/, .windsurf/, and OPENCODE.md are generated
from .promptscript/. Edit PromptScript sources, then:
promptscript validate --strict .promptscript/project.prs
promptscript compile --all-builds --force --strict
promptscript compile --all --force --strict
go run ./tools/validate -patch-opencode
The final command applies the git-byline patch to the generated OpenCode
plugin (bounded file paths, apply_patch paths, and awaited hooks) and syncs
its copyable harness template. It also adds a read-only permission block to
the generated OpenCode subagents, because PromptScript does not carry their
tools list into OpenCode. The block keeps OpenCode's default prompt before
.env files. The patch also pins the generation time in the subagent stamps,
because every compile would otherwise move it and leave a diff. Review the
generated diff. Never edit generated instruction files directly.
The OpenCode setup command, marketplace/harness/opencode/git-byline-setup.md,
installs the plugin from a release tag and checks its SHA-256. When the plugin
changes, go run ./tools/validate fails and prints the new digest. Copy it
into both code blocks of the setup command. Leave the release tag alone,
because Release Please rewrites it.
Release Please owns CHANGELOG.md, release versions, release pull requests,
and tags. Do not hand-edit release output except while bootstrapping an empty
changelog.
Branches and commits
Create a focused branch from main. Use Conventional Commits with an
imperative subject, no trailing period, and at most 70 characters.
Allowed types:
feat fix docs test refactor chore ci perf revert build
Use fix(deps) for runtime dependency updates, chore(deps-dev) for
development tools, and chore(ci) for action updates.
Pull requests
Every pull request must explain:
- behavior and rationale;
- compatibility and migration impact;
- exact validation commands and results;
- tests and documentation;
- generated artifact impact;
- release impact;
- security and privacy impact.
Link an issue for non-trivial work. CODEOWNERS review is required for automation, security, release, storage, notes, Git execution, and hook paths. Squash merge is the default.
Contributions are licensed under the MIT License.