On 6 August 2015 at 19:59, M.-A. Lemburg <mal@egenix.com> wrote:
> I had mentioned a fourth one:
>
> 4. Add a NEWS field to the issue tracker and use it's content
> for the file entry
>
> This is how eGenix does it and it's been working great so far.
> We simply have our issue tracker generate a report and use
> this as basis for the change log when cutting a release.
>
> The advantage over checkin messages is that you are not stuck
> if you have multiple checkins for a single issue which should
> only have a single entry in the change log.
>
> Without using the issue tracker, this is similar to approach
> #2 you mentioned above, but with only creating that file
> once during the release process instead of patching it up with
> every single checkin.
This is fairly similar to the way Red Hat does it for downstream
products - the docs team figure out the Errata text for end users
based on the bug, then that's mapped to the right places accordingly.
Eventually pursuing that approach would give us a few rich tiers of information:
* full commit logs
* commit logs filtered to just be those which mention bug numbers
* issue tracker NEWS items mentioned in commit entries
* the What's New documentation
However, given that we're always going to be able to generate full
commit logs, and the filtered logs that mention issues, I think that
makes for a good place to start, even if we end up adding a new field
to the tracker later. After all, we'll always need to write commit
messages regardless of what else we do.
What is "that"? You forgot to specify which alternative you were proposing to use as an interim to adding a field to the issue tracker.
Something I *would* like to address up front is how we're going to
deal with errors in commit messages (especially cases where we've
failed to mention an issue number, or have mentioned the wrong one).
Does this mean you are talking about proposal #3 (generating from commit message)?
However, having a commit log based generator offers a relatively
decent way to deal with that: a Misc/NEWS.overrides directory, with
filename prefixes based on the commit hashes to be overridden.
This is making me prefer MAL's #4 solution.
Dealing with the forward merges will also be necessary - existing
projects https://pypi.python.org/pypi/gitchangelog may provide useful
ideas on that front.
I would simply ignore merge commits. It's implied that anything fixed in the previous minor release applies to the default branch. Once again, MAL's approach helps with this as we would simply check the Versions field.
If we wanted to get particularly fancy, commits that added
versionadded and versionchanged tags to the documentation could also
be automatically highlighted.
Regardless, I think one thing I'm figuring out from this discussion is
that there *shouldn't be* a NEWS file in the repo itself - the repo
will contain the source data, but the rendering can happen separately
rather than being done incrementally on each commit. This means that
the renderer can be developed in parallel with the current process,
with some seed data used to capture the state of the NEWS file as of a
particular commit.
After this email I'm now supporting MAL's idea #4. We can make the field required when the Resolution is set to Fixed. I would even potentially argue for a dropdown for What's New inclusion to flag whether a What's New mention is warranted. By making this a required field to set it would greatly simplify the writing of that doc later by having a generated list of all issues that require a mention, effectively creating a TODO list instead of having to hunt through all commits or the entire changelog (and I don't think we can ask non-core contributors to provide What's New text if we want to keep the quality of that doc high).