OpenZeppelin / OpenZeppelin/compact-contracts
Define and improve changelog entries
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 55
- Forks
- 29
- Avg merge
- 5d 7h
- Merged PRs (30d)
- 25
Description
As of now, this repo follows: https://keepachangelog.com/en/1.1.0/. They list their guiding principles and number one is: "Changelogs are for humans, not machines"
In the spirit of keeping a good, consistent, and readable changelog for humans (our users), I propose that a simple question should be asked and the answer decides if an entry should be included: "Will users notice this change and/or will they have to do something different on account of this change"
Entries worth including:
- Change circuit signature
- Change circuit behavior
- Add new circuit/module
- Remove circuit/module
- Fix bug in circuit
- Update compiler/language version
Noise that should be avoided:
- Fix doc typo
- Add test scaffolding (internal use only/not shipped)
- Reorganize repo structure (if import paths stay exactly the same)
- Change variable name in circuit body
- Consolidate checks in CI
- Bump
turbotov1.2.3
Also, LLMs are trained to be complete and justify that work was done by default. Therefore, LLM-created entries tend to look like giant, uninviting walls of text. I recommend that entries should lean toward brevity when possible. If there's a relevant change that a user is interested in, they should go to the referenced PR anyway for details
There are definitely cases that sit in a grey area and that's totally okay. It's an art to consolidate hundreds or thousands of lines of code into a small, easy-to-read entry
Favor something closer to this:
- Change return types in
SpiceGirlsNFTmodule (#123)Sporty(): Uint<4>->Uint<8>Ginger(): Field->Uint<4>Baby(): QualifiedShieldedCoinInfo->ShieldedCoinInfoScary(): Vector<2, Bytes<32>>->Bytes<16>Posh(): JubJubPoint->Secp256k1Point
as opposed to this:
- Refine and modernize the return type signatures across the
SpiceGirlsNFT
module as part of our ongoing effort to improve type safety and better model
the domain. Each getter was reviewed individually and its return type
reconsidered from first principles.Sportypreviously returned aUint<4>,
which the team felt was unnecessarily restrictive given anticipated future
growth, so it now returns aUint<8>. This is fully backward compatible
since everyUint<4>value fits comfortably within aUint<8>. Conversely,
Gingerwas returning aField, which we determined was over-provisioned
for its actual usage, so it has been tightened to aUint<4>to more
accurately express intent.Babynow returns aShieldedCoinInforather
than aQualifiedShieldedCoinInfo, a simplification that removes a field
consumers were rarely using in practice.Scaryhas been consolidated from a
Vector<2, Bytes<32>>into a singleBytes<16>, which is more compact and
reduces storage pressure. Finally,Poshnow returns aSecp256k1Point
instead of aJubJubPoint, aligning it with the curve used elsewhere in the
multisig modules for consistency. Internally,_ifYouWannabeMyLover(not
exported) was updated accordingly as was_youGottaGetWithMyFriends.
Furthermore,_zigAZigAhnow short-circuits in the common case. We added 23
new tests, bringing the module to 91% coverage, introduced
test/mocks/MockSpiceGirlsNFT.compact, and re-ran the full suite on both
runners. The naming of these circuits is unchanged and remains an intentional
design decision. No migration is required. Credit to@sportyspicefor spicing
up our lives. (#123)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the repository's current changelog and any contribution or release guidance. Compare the existing entries with the proposed user-focused, concise criteria, then document an agreed policy with representative examples; done means maintainers have a clear rule for deciding what belongs in the changelog.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, release
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100