github.com/quay/claircore@v1.5.28/docs/contributor/changelog.md (about)

     1  The claircore project has switched from a [`git log`][log1] based changelog to a
     2  [`git notes`][notes1] based changelog.
     3  
     4  This has the benefit of making the changelog more human-friendly, as it can have
     5  prose describing changes now, but makes adding entries a bit more involved. A
     6  full understanding of `git notes` is helpful for working with the changelog, but
     7  not required. If the reader has worked with the `notes` feature before, the
     8  changelog entries are stored under the `changelog` ref. For other users, there
     9  are some helper scripts in `.github/scripts`.
    10  
    11  ### Basics of `git notes`
    12  
    13  `Git notes` is a mechanism for storing additional information alongside commits
    14  without modifying the commits. It does this by creating a ref full of files
    15  named after the commits, with their contents being the notes. This scheme
    16  requires some special care and tooling -- see [the documentation][notes1] for
    17  more information.
    18  
    19  ### Helper scripts
    20  
    21  The primary helper script is `changelog-edit`. It allows a user to sync down
    22  notes, edit an entry, or both. See the output of the `h` flag for more
    23  information.
    24  
    25  The other script of interest is `changelog-render`, which can be used to render
    26  out the changelog on demand, assuming the changelog notes have been pulled
    27  locally.
    28  
    29  The `changelog-update` script uses `changelog-render` to add to the
    30  `CHANGELOG.md` file in the repository root.
    31  
    32  ### Formatting
    33  
    34  Broadly, changelog entries should be formatted like commit messages without any
    35  trailers. Entries are turned into list items, with the subject being the bullet
    36  point and the body of the entry being the "body" of the item, or hidden behind
    37  `details` elements when using HTML-enabled output.
    38  
    39  The entries are almost always rendered as markdown, so using minimal markdown is
    40  OK. Anything requiring excessive markdown is probably better served as
    41  documentation proper, rather than a changelog entry.
    42  
    43  [log1]: https://git-scm.com/docs/git-log
    44  [notes1]: https://git-scm.com/docs/git-notes