OpenZeppelin / OpenZeppelin/compact-contracts

Define and improve changelog entries

Open
#912 0 comments 0 reactions 0 assignees View on GitHub

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 turbo to v1.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 SpiceGirlsNFT module (#123)
    • Sporty(): Uint<4> -> Uint<8>
    • Ginger(): Field -> Uint<4>
    • Baby(): QualifiedShieldedCoinInfo -> ShieldedCoinInfo
    • Scary(): 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. Sporty previously returned a Uint<4>,
    which the team felt was unnecessarily restrictive given anticipated future
    growth, so it now returns a Uint<8>. This is fully backward compatible
    since every Uint<4> value fits comfortably within a Uint<8>. Conversely,
    Ginger was returning a Field, which we determined was over-provisioned
    for its actual usage, so it has been tightened to a Uint<4> to more
    accurately express intent. Baby now returns a ShieldedCoinInfo rather
    than a QualifiedShieldedCoinInfo, a simplification that removes a field
    consumers were rarely using in practice. Scary has been consolidated from a
    Vector<2, Bytes<32>> into a single Bytes<16>, which is more compact and
    reduces storage pressure. Finally, Posh now returns a Secp256k1Point
    instead of a JubJubPoint, aligning it with the curve used elsewhere in the
    multisig modules for consistency. Internally, _ifYouWannabeMyLover (not
    exported) was updated accordingly as was _youGottaGetWithMyFriends.
    Furthermore, _zigAZigAh now 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 @sportyspice for spicing
    up our lives. (#123)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.