Open bitprophet opened 6 years ago
For myself personally, I appreciate the ability to review the Changelog from one place within the source files of my project; I refer to the source changelog.rst
much more often then the rendered version.
For the projects I've been involved with, they're been small and so I haven't run into the issues of serious merge conflicts like you describe above.
But for merging up long running branches, maybe it's actual a feature to either work through the merge conflict, or prep the changelog so there isn't a merge conflict (perhaps by backporting the changelog updates), because it forces you to explicitly decide which release lines your new feature or bugfix should be released on.
It feels to me like there are tools out there that have attempted some of these other approaches (and ran up against the tradeoffs):
I think releases strikes a good balance here, and I'd recommend that releases not try to re-invent itself.
This is just spitballing so I don't forget N months from now.
The current curated-changelog-file approach works well enough, but has frustrating side effects I've never found solutions for, such as all the merge conflicts when doing a 'merge-up' from old branches through newer ones. These are usually easy to resolve, but it's still irritating gruntwork/friction, removal of which was the whole point of Releases...
That's on top of the issues endemic to this approach, such as the need for complex logic to figure out which release lines a given issue is, or should be, included within. When the project began, this work seemed a necessary tradeoff vs "use your git commit messages" or "100% manually edited NEWS/CHANGES files" (I contrasted these approaches in http://bitprophet.org/blog/2013/09/14/a-better-changelog/).
I've recently been acting as a sounding board for some colleagues trying to grow an early-stage internal project into a more mature, public-facing one, and was pitching them on using Releases or some variant thereof.
They like the overall approach but are, understandably, leery about the merge-conflict thing. What's an annoyance for a single maintainer like myself would become unreasonable friction for a full team (especially one currently used to the low-friction anything-goes rolling-non-release approach.)
What follows are some ideas about alternatives that came out of that discussion.
The core idea is to replace the changelog file with some other 'format' or data source that is more resistant to merge conflicts, and which is dead simple for developers to interact with (two arguably separate concerns.)
The biggest class of approach being considered is to go back to the "git commits" style of changelog data source:
[ci skip]
for example) commit messages for use in the changelog.[support] does support things
? This conflicts with a commit message's "real" functionality of labeling what that specific commit changed.git commit --allow-empty
lets you add an empty commit to the tree! Normally that's a silly thing to do, but in this case it lets us add Git-level metadata, basically treating Git like the database.All that said, I wonder if there's a middle ground not relying (entirely) on Git metadata? If the core problem being solved is the merge conflicts in a single changelog file, could we do other wacky stuff instead? E.g.:
The dump above covers both my own thoughts & those of the internal team I mentioned. Re: Releases itself, I'm torn.
For my own personal use (which is of course how it began), I'm tempted to investigate the annotated-git-commits approach - annotating some of my commits and/or doing occasional 'empty' commits seems like a compelling alternative to the increasing number of merge conflicts I'm dealing with (especially as we move into multiple major release families.)
The big downside is that this approach requires git tomfoolery at changelog creation time and spoils the "purity" of the current setup: you can no longer render the changelog from a static copy of one's Sphinx sources!
One must expect either: