Understanding of "Unrelease" section

[buhtz]

Hi, I try to understand some details.

I know the FAQ entry about the fact that common changelog do not have an "Unreleased" section on top of the changelog compared to keep a changelog.

My primary question is how I should keep track of changes in the main branch if I am not allowed to write them down to the changelog? I can not use the commit history because commits are for developers and machines and not for users. The changelog is for users not developers. That is the difference. Because of that difference I am also not allowed to just collect all commit messages and copy and paste them to changelog.

Your FAQ entry says in its first paragraph that it is "unproductive". I don't understand it. Can you explain it in more details?

Although a commit or pull request could describe itself in the Unreleased section, it cannot add the necessary (self) references. These can only be added after the fact.

I would argue that I don't use PR numbers or commit hashes in the changelog. I do use Issue numbers and they are present.

First-time contributors can't be expected to update the changelog. Maintainers would have to commit that separately, resulting in a noisy git history.

No problem with that. As a maintainer i do review every PR from first-time contributors. I say them to add a changelog or I modify their PR (via clone from their fork and push to it) directly before merging it. It is a usual workflow in my project.

Writing a changelog requires a bird's-eye view of the project, while individual changes are typically best reviewed and discussed in isolation.

I don't see this as an argument about not having an "Unreleased" section. Discussion and review of a change happens in the Issue first and ends in the PR. That is isolated. And as a maintainer I do have a bird's-eye. There is no PR without review. Even if there is no second reviewer I do review my own PRs after a cool down phase (min. a week).

[buhtz]

I read your "hallmark" docu and now better understand your workflow. It make sense. But I think it is a good example about how different workflows can be.

In the context of "Common Changelog" as a standard I would argue that "Unreleased" sections should be allowed. They might not making sense in your workflow but in mine. And your workflow do violate another general or often read rule: Don't create your changelog based on commit messages. It is a rule for beginners. In your specific case you do rewrite and rephrase your commit messages in the changelog. This is OK. But this won't work for a beginner or a beginner do not understand the diff between a commit message and a changelog entry. I assuming this is the reason why you often read that beginner rule.

I will try "hallmark" in one of my one-man-projects and maybe adapt it later in Back In Time where I have to convince a bigger team. ;)

I appreciate your work and your effort. It really adds something to the FLOSS universe.

[vweevers]

In the context of "Common Changelog" as a standard I would argue that "Unreleased" sections should be allowed. They might not making sense in your workflow but in mine.

Fair enough. I'm somewhat open to restoring the "Unreleased" section, as an optional feature. But, I don't really like to make commit hashes optional because as a developer reading changelogs I find them to be essential in understanding what really changed (language has its limits, code is less ambiguous).

Don't create your changelog based on commit messages.

I actually recommend it. Writing changelogs has helped me to write better commit messages and vice versa. Generating a changelog from commit history is by itself not a problem, and can increase productivity for both the writer and reader (being able to recognize a change in different contexts).

[buhtz]

Now knowing "hallmark" I do understand your workflow. I do understand your need for commit hashes. But additionally I do have a need for a Issue or PR reference because the commit hash often don't allow me to know what PR/Issue was involved. It should be in the commit message but sometimes is not.

I will try the without-Unrelease-section-but-hallmark-workflow in one of my tiny one-man projects.

Off topic: How should a commit message look like that "hallmark" will create a changelog entry with commit hash plus Issue/PR number in it? I would suggest you to improve your hallmark docu and explain the workflow on an example like you would do it in a tutorial.

[vweevers]

How should a commit message look like that "hallmark" will create a changelog entry with commit hash plus Issue/PR number in it?

The Common Changelog format for references (to issues and commits) is an extension of how GitHub inserts PR numbers into commit messages. For example, if you squash and merge a PR called Fix typo then the resulting commit message is Fix typo (#6). See https://github.com/vweevers/common-changelog/pull/6 and the resulting https://github.com/vweevers/common-changelog/commit/84b31de06304f203cc7521fcc6b19cea7380fd35. If we generate a changelog from that then hallmark inserts the commit hash, giving us:

Fix typo (#6) (84b31de)

Since recently, hallmark also parses git trailers. For example, if the original commit message was:

Fix typo

Closes: #23

Then hallmark would turn it into:

Fix typo (#23) (84b31de)

[hcording]

I agree that an unreleased section should be allowed. Django uses such a section but includes the next upcoming version, which I find useful. E.g.:

# Changelog

## [5.1.0] - UNDER DEVELOPMENT

### Changed

- ...

...

[5.1.0](https://github.com/repo/repo/releases/tag/5.1.0)

The URL to 5.1.0 could either be left out until the release, or kept in, since after a release is published the link will work even for past versions of the repository.

I also think it's not too much to ask contributors to add to the changelog. If they mess it up in the PR, they can always get feedback and improve the entry. After squashing, these "fixed ..." commits will not clutter the git history anyways.

Any thoughts are welcome!