HarperFast / HarperFast/code-guidelines

Document commit signing: rationale, setup, and org-wide enforcement

未关闭
#12 0 条评论 0 个 reaction 已指派 1 人 已被 @Ethan-Arrowood 认领 在 GitHub 查看
主要语言
JavaScript
星标
3
派生
0
PR 合并指标
30 天内没有已合并 PR

描述

## Summary

Write a commit signing guideline doc. We want to enforce commit signing across the org — all commits to all HarperFast repos, with public-facing OSS repos as the highest priority, should be signed.

## Doc outline

The doc should be structured in this order:

### 1. Why commit signing matters

Open with the rationale: signed commits cryptographically verify that a commit actually came from the person it claims to be from. Cover the threat model briefly — author spoofing (anyone can set `user.name`/`user.email` to anything), supply chain integrity for our OSS consumers, and the "Verified" badge as a trust signal on public repos.

### 2. How to set it up

Link out to setup resources rather than duplicating them:

- [GitHub: About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
- [GitHub: Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
- SSH key signing (the lowest-friction option for most people): [Telling Git about your SSH key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)
- GPG setup for those who prefer it
- Note on signing via the GitHub web UI (web-created commits are automatically signed by GitHub)

### 3. How we enforce it

Link to the enforcement mechanisms and document which ones we use:

- Org-level: [rulesets at the organization level](https://docs.github.com/en/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization) with the "Require signed commits" rule
- Repo-level: branch protection / repo rulesets requiring signed commits on default branches
- Document the actual settings we apply so repo admins can verify their repo is compliant

### 4. AI agent workflows

Platform enforcement (rulesets, CI, hooks) is the backstop, but AI agents are a major producer of commits and a major reviewer of PRs — the guideline should be embedded in agent workflows too, especially in the window before hard enforcement is rolled out:

- **Producing commits**: skills / agent instructions (e.g. in the `skills` repo, `CLAUDE.md`/`AGENTS.md` conventions) should instruct agents that commits they author must be signed — verify the environment's signing config (`git config commit.gpgsign`, signing key present) before committing, and surface a warning rather than silently producing unsigned commits.
- **Reviewing PRs**: PR-review skills should include a commit check step — flag unsigned/unverified commits in review output. This gives us soft enforcement via agent review before org rulesets are turned on.

The doc should note this pattern; actually updating the individual skills can be follow-up work.

### 5. Effective date

Short closing section: this policy was adopted in **July 2026**. Enforcement applies to commits from this point onward — historical unsigned commits are grandfathered in and do not need to be rewritten. Only new commits are required to pass signature verification.

## Acceptance criteria

- [ ] Doc added to this repo following the sections above
- [ ] Enforcement settings (org ruleset and/or repo-level guidance) documented
- [ ] AI agent workflow guidance included (agents sign their commits; review skills check for signatures)
- [ ] Effective date (July 2026, forward-looking only) stated

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。