Project

General

Profile

Task #1214

Keep track of important changes for Changelog

Added by Roland Schulz over 6 years ago. Updated about 6 years ago.

Status:
New
Priority:
Normal
Assignee:
Category:
documentation
Target version:
-
Difficulty:
uncategorized
Close

Description

We need to agree on some mechanism to keep track of important changes so that those are not forgotten for the Changelog.
I suggest either:
  • create a wiki page already now and add important things there as soon as there are merged
  • create a changelog file in the source and add important changes there
  • agree on some special tag in the commit message which can be parsed to create the changelog

History

#1 Updated by Roland Schulz over 6 years ago

An example is 2308 which changes vdwradii.dat and thus changes the results of a couple of tools.

#2 Updated by Mark Abraham over 6 years ago

Yeah, we should do better with this, rather than leaving it all to the period before a release, when the detailed context has been forgotten.

Using a "git note" (https://www.kernel.org/pub/software/scm/git/docs/git-notes.html) is a possible solution. Can be added after the fact, and thus does not form part of the commit SHA. Even "Note: should appear in ChangeLog" can be sufficient. Of course, many substantive commits will appear in the ChangeLog even if there is no note, but if there's an easy way for someone to take some action when the idea is fresh, that is best. Keeping the note linked to the commit and its SHA makes it easy to find discussion in Redmine and/or Gerrit when the time comes to convert the note into ChangeLog text, and as the person likely to be doing that work, that linking is extremely attractive!

Using a webpage makes some busywork making links, keeping branches straight, remembering to add to the ChangeLog only after merging, etc. But that's a plausible approach.

Would prefer not to have a ChangeLog in the repo, since that'll lead to commits that only hit the ChangeLog. Tags in the commit message can be a bit noisy too, particularly if the text for the ChangeLog is suggested with the note (and maybe duplicating some aspects of the commit message...).

#3 Updated by Mark Abraham over 6 years ago

Basically, data about the data should be linked to the data, and not in the data!

#4 Updated by Mark Abraham over 6 years ago

It turns out Gerrit makes notes already - see bottom of https://github.com/gromacs/gromacs/commit/ca99be56a0fb6eeeac1c88b99fd8c5ad0ff01c1d. Not sure how to import those into local repo.

#5 Updated by Roland Schulz over 6 years ago

git fetch origin refs/notes/*:refs/notes/*

See http://git-scm.com/2010/08/25/notes.html

I wouldn't use notes because
- it is one more thing for people to learn
- they can't be reviewed / easily edited with history

I doubt we would update the changelog so often that the number of extra commits would be an issue.

#6 Updated by Mark Abraham about 6 years ago

  • Assignee changed from Justin Lemkul to Mark Abraham

In practice, reconstructing the release notes for patch releases from the git log is tedious, but about the same work as doing it incrementally. So I think the need for any particular solution is low. I still don't like a ChangeLog in the repo, because it is one more thing to let get out of date.

#7 Updated by Roland Schulz about 6 years ago

But the problem with doing it with the release is:
- important things might be forgotten
- it is difficult to spread the workload.

#8 Updated by Mark Abraham about 6 years ago

Sure, but relying on the accuracy of whatever ChangeLog infrastructure exists can also lead to forgetting important things. Already we occasionally forget to link fixes to open Redmines.

The truth of the git log is a pretty good start, though. All that I have been doing is postprocessing the log, roughly sorting by topic, and making Redmine links.

We could open the release notes on the webpage for an upcoming release in advance (noting that this is for unreleased code) so that people who want to be sure something hits the release notes can write something where it will get noticed.. It's such boring and thankless work that I expect few people to help, though!

Also available in: Atom PDF