vweevers / common-changelog

Write changelogs for humans. A style guide.
https://common-changelog.org
MIT License
107 stars 8 forks source link

Improve formatting for single contributor in release #9

Open PaulRBerg opened 1 year ago

PaulRBerg commented 1 year ago

I like Common Changelog a lot, but the format is a bit repetitive when all the references are authored by a single contributor. Here's an example from one of my open-source projects PRBTest:

Screenshot 2022-12-06 at 12 36 16 PM

It would be nice if the Common Changelog standard suggested a way to reference a contributor only once when appropriate, potentially underneath the release title or underneath each category:

## v0.2.0

All of the contributions below have been made by @paulrberg.

Or:

## v0.2.0

### Changed

All of the contributions below have been made authored by @paulrberg.

- Set cheatcode mutability/ visibility
- Split `Vm` in `Vm` and `VmSafe` interfaces

I know that the current standard recommends that:

If the project only has one contributor, author names can be omitted.

But there can be the situation (in fact, I would argue that this is the most common situation) when the project as whole as multiple contributors, but one particular release is handled by a single contributor.

What do you think?

vweevers commented 1 year ago

This is also common in my projects, but I don't mind the repetitiveness (anymore). Having author names in a consistent place makes a changelog easy to scan. In contrast, the "All of the contributions below ..." line has to be read in full in order to understand it. Putting it under the release title would conflict with notices which are intended for important notes only. We could perhaps introduce "footnotes" (i.e. arbitrary markdown content below the release) but it could invite misuse.

PaulRBerg commented 1 year ago

Makes sense to me. I suggest we keep this issue open in case others will share their feedback in the future.

bessman commented 8 months ago

I recently came across Common Changelog and have started using it in my own projects. Here's how I have been handling change authorship:

For projects which I own (i.e. they live under my github username), I never specify author unless a change was authored by someone other than myself. For such projects, the repo owner can be assumed to have authored any changes unless otherwise specified.

For projects owned by organizations (which typically have multiple significant contributors, especially over time), I always specify the author of every change, even if I am currently the only active maintainer.

If a project owned by an individual is transferred to an organization, that must be stated in the changelog. Any changes made prior to that point can be assumed to have been made by the original owner, unless otherwise specified.