HarperFast / HarperFast/code-guidelines

Define commit standards: authorship, AI attribution, and trailers

オープン
#13 コメント 0 件 リアクション 0 件 担当者 1 名 @Ethan-Arrowood が担当を希望しています GitHub で見る
主要言語
JavaScript
スター
3
フォーク
0
PR マージ指標
30日以内にマージされた PR はありません

説明

## Summary

Write a commit standards guideline doc. Initial scope is authorship and attribution — who a commit is credited to and how AI involvement is disclosed — plus an exploration of commit trailers and eventual enforcement. Keep everything in this one issue for now; enforcement work can be split into sub-tasks later once we've settled the guidelines themselves.

## Doc outline

### 1. Authorship and AI attribution

- Every commit must have a **human primary author**. The `Author` field is always a person, never an AI agent or bot identity.
- AI-generated or AI-assisted commits should attribute the agent via a trailer — `Co-Authored-By:` is the current convention (e.g. what Claude Code appends), but the doc should confirm that's the trailer we want, or propose a better-suited one if the ecosystem has converged elsewhere.
- Define where the line is: does tab-completion count? Does an agent writing the whole diff? The doc should give practical guidance so people aren't guessing.

### 2. Trailers: `Signed-off-by` and the DCO

Explore whether we should adopt `Signed-off-by` (as used by the Node.js project and the broader Linux/DCO ecosystem):

- What it actually asserts ([Developer Certificate of Origin](https://developercertificate.org/)) vs. what commit signing asserts — they solve different problems and the doc should make that distinction clear
- Whether it makes sense org-wide, only for public OSS repos accepting external contributions, or not at all
- If adopted anywhere, when it's most appropriate (e.g. repos with outside contributors where provenance/licensing assertions matter)
- Recommendation with rationale — it's fine for the answer to be "not now, revisit when X"

### 3. AI agent workflows

These standards should be embedded in agent workflows, not just written down for humans — agents both author commits and review PRs, and skill-level guidance gives us soft enforcement before any tooling exists:

- **Producing commits**: skills / agent instructions (`skills` repo, `CLAUDE.md`/`AGENTS.md` conventions) should encode the authorship rules directly — human as primary author, agent attributed via the agreed trailer, plus any trailer conventions we adopt (e.g. `Signed-off-by` where applicable). Agents following the standard by construction is cheaper than catching violations after the fact.
- **Reviewing PRs**: PR-review skills should include a commit-hygiene check — verify authorship/attribution trailers are present and correctly formatted, and flag violations in review output. This is our interim enforcement layer until (and even after) automated linting exists.

The doc should describe this pattern; updating individual skills to implement it can be follow-up work alongside the enforcement sub-tasks below.

### 4. Enforcement (exploratory — likely future sub-tasks)

We do very little commit linting/enforcement today. The doc should explore options without committing us to rolling them out everywhere:

- Commit message linting (e.g. commitlint, gitlint) — what we'd check (trailers present, author format) and where it would run (CI, merge queue)
- GitHub-side options: rulesets with metadata patterns, required workflows
- DCO enforcement apps/actions if we adopt `Signed-off-by`
- Explicit note that **guidelines can be adopted before enforcement exists** — deciding the standard and enforcing it org-wide are separate efforts, and enforcement is a heavier lift we can stage later. Skill-embedded guidance (§3) is the lightweight interim layer.

## Acceptance criteria

- [ ] Doc added to this repo covering authorship, AI attribution, and the trailer exploration
- [ ] Clear recommendation on `Signed-off-by`/DCO adoption (including "not yet" as a valid outcome)
- [ ] AI agent workflow guidance included (agents follow the standard when committing; review skills check commit hygiene)
- [ ] Enforcement options surveyed, with candidate follow-up sub-tasks identified but not yet filed

## Related

- #12 (commit signing) — signing verifies *who pushed the bits*; this doc covers *how commits are attributed and formatted*. The two docs should cross-link.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。