Keep a Changelog
keepachangelog.com
keepachangelog.com
And this is exactly the opposite of a git commit only changelog. They put great effort in it so that everybody wait for it eagerly, and it might one of the reasons they got lots of sponsors and users donations.
My question is - is there any tool that one could use to quickly capture a few seconds of a selected region of the screen as a video/GIF? Preferably one that would subsequently allow to throw away some frames from the beginning and ending. Such a tool would speed up the process of creating visual changelogs quite a bit.
https://www.debian.org/doc/manuals/developers-reference/ch06... https://www.debian.org/doc/debian-policy/ch-docs.html#s-chan...
The activities of programmer-archaeology are always made so much easier if you have a screed of history for each area of interest in the codebase. Sadly that's still rare, even in groups that do the necessary work to maintain their documentation for the current state of HEAD. There are many times when history matters, is relevant, and those who do not learn it are doomed to repeat it - or at the very least build elaborate theories to explain what happened in the past in order to understand how the present came to be where it is.
The great changelog built on great commit history is probably hard to do outside of a small, focused group. On the other hand, the pull request process has emerged and developers have embraced that level of work, so it feels like it should be achievable.
It's strange to me that anyone would consider especially open source software as something so good and obviously beneficial that the archeology you mention would be a fact of life for end-users. It betrays a misconception about the value of software in a vacuum: without tests, code documentation, interface design, and change documentation (a changelog).
The best algorithm is useless without proper tests verifying how it functions against real input; it's obscure without good documentation highlighting its quirks and design decisions, and if it evolves without clear explanations within a changelog then the changes in its behavior will remain mysteries to end-users as long as they don't go deep inside the code to understand how it worked before and how it works now.
I've had to do this kind of programmer-archeology on numerous production dependencies (transitive or otherwise) in the past and the resulting frustration is very much the fuel that motivated me to make keepachangelog.com
An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.
Writing a changelog progressively is the only way you’re likely to end up with it being good. Consider the whole point of the “unreleased” section, too. If you put it off, you’ll just keep on putting it off, and when you finally do make a release you’re unlikely to put enough effort into the changelog.
Your changelog will be better if you write it at the time of development, not release. To be sure, you’ll want to check over it at release time or even before then, but there’s no rule against amending the changelog at any time.
I'd agree this is an area we need to clarify for version 0.4.0 and forward.
I wish that you could specify merge behaviour on a file-by-file basis for something like Git, even as simple as “don’t worry about the text before when adding lines, just anchor it to the text after” which would equate to “append to section” in the earlier outlined case.
Generally people edit changelogs after pull requests have been merged or as part of the pull requests themselves. It's far easier to figure out merge conflicts if and when other versions appended to the changelog simultaneously because all changelog entries are dated (or at least they should be) or at least versioned and contain plain text.
That said I agree that we should probably spend some time detailing common processes for editing and appending to a changelog in situations with concurrent branches being developed.
This is only a problem if you're handling multiple PRs simultaneously so your project has to reach a certain level of use before you'll see it.
An open source project like Rails has different components all developed within a single repository although they're packaged up independently for release. Each different component has a root level changelog that documents its changes and there isn't a centralized changelog for all of Rails. In some ways it's problematic because you can't see a merged changelog for all core components of Rails but it's also useful when you're only worried about changes to the ORM component since you'll only see changes pertaining to it within its own changelog.
In my mind a changelog is a root-level concern for a single piece of software, regardless of how many isolated components it's composed of. Basic tooling should be able to centralize each changelog (as long as versions are synchronized, but that's another issue) and ideally you should be able to filter by sub-component.
This is definitely not something we've created any guidelines for yet. So if you have any thoughts on the matter, feel free to suggest them: https://github.com/olivierlacan/keep-a-changelog/issues
I've covered these recent changes in a post that didn't quite make it to the front page recently: http://olivierlacan.com/posts/logging-changes-all-over-the-w...
Do use ChangeLog format for commit messages!
This is calling for more use of what GNU calls a "NEWS file" (https://www.gnu.org/prep/standards/html_node/NEWS-File.html), which is what virtually everybody else means when they say "changelog". Per the page itself:
> Why can’t people just use a git log diff?
> Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states.
> As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.
I've got a command that will add everything that has changed in a directory tree except for ignored files, into a commit. And it is very helpful to write in the commit exactly what you're doing . You do this once a day and you've got an excellent log not only of how you have changed things but you can hop back to a previous commit and reset to a previous day.
Now when it comes time to create a pull request ...
Then you can go back and rebase and squash from the original start, and things into a commit history that is explainable and readable for the project. The only thing that would make this even more seamless if you could do a split-squash where you take a commit, "ungroup" it into its individual changes, then put the changes into their respective commits, and then squash those with the commits for what something should be at the end point.
I find that seeing the exact changes you're about to commit does lead to more detailed git commit messages, although the maximum length of most "properly" written commit message titles (50 characters) tends to hinder the quality of commit message titles as entries in a changelog. They're often very high level summaries of introduced changes and it's common for people to focus on the change at hand — not on its impact on end-users — when writing a commit.
Again, this all goes back to the intended audience for commit messages compared to change logs. If the end users of the projects you work on diligently read every commit in the project history, then I dare suggest you're in a rare and privileged situation. I don't expect end-users of most open source software to be satisfied with either the high-level nature of commit titles, or their minutia. This leads me to think that keepachangelog.com needs to gather more examples of the of changelogs I advocate for. It seems that a surprisingly small number of people have encountered them.
Rebasing and squashing commits to clean them up to be changelog-worthy does not solve the 50-character issue with conventional commit titles I mentioned above. It also doesn't solve for situations with collaborative pull requests or branches. That is, unless there's a clear process for squashing and rebasing being done by a single person at the very end of the project. I think it's more realistic to expect a single file changelog to be regularly updated (through an Unrealeased section) as changesets are being introduced prior to a release and to eventually update this same single file when the group of changesets is about to be released under a new dated version release.
In my experience, they aren't. They want a top-level view of why/if they should upgrade.
In my dayjob, when preparing a release, we use tools to dump the git commit messages into the head of the CHANGELOG, then edit it back into user-facing text. We omit changes that are not user-facing (eg. 'gem you've never heard of upgraded to 0.4.4') and focus on changes they care about (eg. 'Redact credentials from URLs in a cached buildpack's output'). See for example our Ruby buildpack CHANGELOG[0].
We build our own binaries for buildpacks. So in addition, for our Github releases, we take the CHANGELOG entry and append a table of supported binaries and default versions[1]. These show up in the CHANGELOG only if we add or drop a core binary.
We work out of Tracker, so we link to Tracker stories, bugs and chores for every mentioned in the CHANGELOG or release notes.
[0] https://github.com/cloudfoundry/ruby-buildpack/blob/master/C...
[1] https://github.com/cloudfoundry/ruby-buildpack/releases/tag/...
What is a "git log diff"? I get"
$ git log diff
fatal: ambiguous argument 'diff': unknown revision or path not in the working tree.
Topic subject line, short exec. summary.
Optional: one or more paragraphs discussing the
"why", or any background information, how the
issue was found, why it's significant, how it
relates to something else, or what other changes
is this change a preparation for and so on.
* file1 (function1): This was done.
(function2) That. Typical ChangeLog stuff.
* file2 (function3): Bugfix here, and so on.Code may be read more than it is written, but it is not read far more than either. You really should have both logs: one detailed for development, and one for your users.
Release notes are not logs. They omit changes, and present selected changes in a different order. As soon as you have two sets of release notes for two releases in one file, then it's becoming a log: a log which captures sequences of release notes. I agree of keeping such a thing rather than giving end users just the notes for the current release.
In any case, developers should not be required to deposit any blurbs into any file as they are committing, regardless of its purpose and style.
Do go ahead and produce release notes, and then keep them in the repository. Do not mix code changes with changes to the release notes file.
There's surely personal bias at play, but I'm far more concerned with people keeping a changelog in the first place to worry too much about how exactly they do it. If Org-mode is what they go with, fine, but what we're facing right now is hordes of open source projects that people end up taking on as direct or transitive dependencies and which do not document their evolution in any meaningful way.