docs: add CLAUDE.md with a CHANGELOG brevity convention - #279
Merged
Conversation
…ntion No CLAUDE.md existed. Add one oriented at AI coding agents: it points to CONTRIBUTING.md as the canonical guide and restates the load-bearing conventions (net8.0 floor, struct hashers, no-alloc hot paths, MinVer owns versioning), plus a dedicated CHANGELOG section codifying the brevity convention — entries stay short and user-facing, no private field names or codegen internals — noting that release.yml extracts each version section verbatim as the GitHub Release body, so terse sections keep releases within GitHub's size limit. Establishes the convention half of #278. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Adds a new CLAUDE.md at the repository root to guide AI coding agents, with emphasis on establishing a concise, user-facing CHANGELOG entry convention aligned with the repo’s release automation constraints.
Changes:
- Introduces agent-focused repository guidance without duplicating
CONTRIBUTING.md. - Documents build/test expectations and key coding constraints (net8.0 floor,
#ifguards, struct hashers, allocation avoidance, MinVer). - Establishes a CHANGELOG brevity convention to avoid exceeding GitHub Release body limits.
…s are equivalent Addresses the review nit on #279: GitHub auto-closes on Closes/Fixes/Resolves alike, so state that the repo standardizes on Closes for changelog consistency rather than leaving the choice ambiguous. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
|
||
| - `net8.0` is the floor. Shared code must not use net9/net10-only APIs unguarded — gate newer paths with `#if NET9_0_OR_GREATER` / `NET10_0_OR_GREATER` and keep a net8.0 fallback. The target list lives in `src/Directory.Build.props`. | ||
| - Coverage is gated in CI: keep line ≥ 95%, branch ≥ 90%. | ||
| - Every public type/member needs an XML doc comment (`GenerateDocumentationFile` is on; missing docs warn). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a
CLAUDE.mdat the repo root (none existed) with guidance for AI coding agents, and — the motivating piece — a CHANGELOG brevity convention.It deliberately does not duplicate
CONTRIBUTING.md; it points there as the canonical contributor guide and only restates the load-bearing, easy-to-get-wrong conventions (net8.0 floor +#ifguards, struct hashers as generic constraints, no-alloc hot paths, MinVer owns versioning) plus a build/test/layout quick-reference.The CHANGELOG convention
The new
## CHANGELOGsection says entries stay short and user-facing — what observably changed and why it matters to a caller, not an implementation walkthrough. No private field names, probe/bit-shift step lists, or JIT/codegen internals; one tight entry per change; end withCloses #NNN.It also records the functional reason, not just style:
.github/workflows/release.ymlextracts each## [X.Y.Z]section verbatim as the GitHub Release body, and GitHub caps that body — so an accumulation of paragraph-per-change entries risks exceeding the limit and breaking the release.Context
[Unreleased]entries — out of scope here).BitSet.Flipchangelog entry as the first example of the target style.🤖 Generated with Claude Code