document how to include changelog in tagged release

[petri]

It seems there's a chicken-and-egg problem: when I generate a changelog (that I want to include in the release), the new version to be made is (obviously) missing from the changelog because it's not tagged yet.

How should this be handled? I could tag a release and then later add the changelog to it but that seems ugly and bad practice - tags should not be modified after creation.

I was looking for a command-line option that would allow to specify the (untagged-as-of-yet) release version so that all the commits since the newest existing tag would be included under that version in the changelog. But it seems that's not possible?

Of course, I can just manually enter the release in the generated changelog, replacing the "(unreleased)" text and then commit the changelog & release. But that extra manual correction should not be necessary, right?

[tuukkamustonen]

I'm using a similar workaround (tag, build changelog, delete tag, commit changelog and tag again). It's not perfect but it works. The suggestion here would make things simpler so +1.

a command-line option that would allow to specify the (untagged-as-of-yet) release version so that all the commits since the newest existing tag would be included under that version in the changelog

[simondrabble]

This seems like a super useful feature. Just started using gitchangelog about ten minutes ago and have already run into this issue.

[znegva]

A workaround is to include something like

unreleased_version_label = "0.1.2 (2017-12-05)"

to your .gitchangelog.rc and update it to the actual version and date before creating a new changelog.

[vaab]

Thanks for your suggestions, these are not ignored, but I'm quite busy lately.

If I understand well, you are using a packaging pattern that actually includes the generated changelog as a file into the actual git managed files. If I understood well and that's effectively your pattern, that's totally respectable and I'll dig into this pattern to understand it fully.

An other packaging/releasing pattern

However, before answering your problem, I just wanted to make sure that you were aware that one of the way of using gitchangelog is to consider that storing the history in git's log is enough, because storing the generated changelog in git would be duplicating information and thus having to face one of the consequence of not following the mantra DRY (Don't Repeat Yourself) : you'd have to take care of keeping these 2 information in sync.

Of course, you need to generate a changelog whenever you have to get rid of your git history, and only then. This happens when you generate a release export (typically to build a .tar.gz, a wheel, or any other actual release distribution format) that requires you to ship the actual release without the git history.

As you probably understand, in this use case, you don't have this chicken-and-egg problem : you tag whenever you want, because you don't ever add the changelog to git history, and you generate the changelog only when creating a release : the creation of the release is a process where you'll naturally get rid of the git history and probably want to set a few other things that are usually programmable and is often automated.

To see an example of this, you might want to see gitchangelog's source code: it hasn't any changelog file managed by git.

unreleased_version_label may be a callable in version >= 3.0.0

I'm perfectly happy however to make your use case easier. I was wondering also about if you saw about the fact that unreleased_version_label can be a callable. However, I'm not sure to understand your packaging pattern enough to make a pertinent example.

pipes and shell wrapper are your friends

What about gitchangelog | sed -r 's/%%unreleased_version%%/$VERSION/g' (don't forget to put unreleased_version_label = "%%unreleased_version%%" in your .gitchangelog.rc ? A simple bash wrapper of 2 lines could make you a new nice gitchangelog command that would accept a new command-line argument exactly as you requested.

Can you explain me your releasing/packaging pattern ?

Do you actually 1- include and commit the generated changelog as a file managed by GIT ? 2- your desire would be to release with roughly the following sequence of commands?

   gitchangelog --unreleased-label $VERSION > CHANGELOG
   git add CHANGELOG; git commit -m "Releasing version $VERSION"
   git tag $VERSION

3- do you have to compile/build/prepare your code to make an actual downloadable release ? If you have links to some of your repository, this would probably help me understand.

Many thanks for your attention.

[petri]

@vaab, thanks for your most excellent response. I am humbled.

You got it right: I had not thought of the "changelog when exported" - pattern that you described. And yes, at least for me, the release/packaging pattern is much as you described (the shell wrapper you provided is a nice helper for that). Most of my packages are setuptools-enabled pure-python packages, so the only extra steps are building a package and uploading to PyPI or a custom package server, sometimes using a release tool such as jarn.mkrelease or zest.releaser, sometimes not.

The pattern you described makes a lot (!) of sense. Yet I still have a nagging desire to check in the autogenerated git changelog. After some self-reflection I realized why; I was hoping to autogenerate:

• generic release notes / package history
• documentation that can be read within services such as github or bitbucket

I can see that using plain git log for release notes / package history might not perhaps be recommendable. At least one should first read through and understand some writings on quality changelogs.

That made me think that I have to try & see if gitchangelog works with git notes and git releases - another story, another issue?

[tuukkamustonen]

I second the need for having CHANGELOG.md inside the repository at all times: it's nice to have in Bitbucket/Github/Gitlab. It's just not as convenient if you have to browse through the git log (that also contains merges, @ignore'd commits, etc.). Attaching changelog to each tag or creating Github-releases is not as convenient either. So yeah, I tend to re-generate and commit a CHANGELOG.md on each release. And while I agree that duplication is bad, when it's automated like here, it's ok.

Answers to your question for me:

1. Yes.

2. gitchangelog --unreleased-label $VERSION > CHANGELOG

   Exactly. Looks good.

   gitchangelog | sed -r 's/%%unreleased_version%%/$VERSION/g'

   A nice workaround.

3. No, not really. No links, sorry.

[vaab]

@petri @tuukkamustonen I religiously respect all usage and am willing to help all use cases if they don't impair with the others, this is why I'm ingenuously interested what place gitchangelog takes in your process. In that regards, I value a lot both of your feedback, as I'm not myself using this process.

@petri regarding your question about github release system, yes, this is very interesting and it has been a while I wanted to have a deeper look at them in my own releasing script (that's why gitchangelog project still does not generate proper downloadable releases here on github). Github release system allows you to build package to be download and as such, is making a clear different code you ship as a package and your versioned source code : leaving space to generate your CHANGELOG automatically when building release files. As a side note, gitchangelog could easily generate a nice AUTHORS file too, and even a NEWS file (that would be an end user targetted changelog).

And yes, @petri, I guess that to offer a real edit-ability of the history that would enable fine tuning of some entry without having to re-edit the entire changelog, git note seem to be the perfect tool. We need to find a nice way to use them to express various changes in changelog entries (removal, edition, addition... etc...).

To move forward on the current issue, would you think that some documentation on some various usage of gitchangelog should be added to the doc ? I'm fearing that the size of the documentation might reachs a tipping point where we'd probably need to switch to full blown documentation and not a simple README file. What do you think about github wiki pages ?

[pauleveritt]

@vaab I'd like to add my support for this. I personally look for a CHANGELOG (or HISTORY) file when browsing repos on GitHub, to see how well they manage their project. I shouldn't look at the commit history. It's for machines, and gitchangelog produces a "beautiful and configurable changelog file". 😃

Also, I might want the changelog as part of the Sphinx docs generated output on RTD. I'd have to do some arranging, to write the output as part of the Sphinx build process before running sphinx-build.

[vaab]

@pauleveritt Thanks for your added feedback. If you have any points where the current gitchangelog was falling short while using it in your release process, feel free to share. There are also some workaround mentioned previously to simplify a little the usage of gitchangelog in some cases. For now, if I'm not misunderstood, this thread is mostly about straightening and probably documenting the usage of gitchangelog in the case of maintaining a CHANGELOG file in the git files.

To make a bolder move, I'm also thinking about a few changes to the code to make the process a little simpler (involving possible command line argument as suggested by @tuukkamustonen ). For the record (and open this idea to discussion): I'm thinking of allowing the config file unreleased_version_label option to access the command line, and provide a quick helper to implement using the value of a command line argument (and documenting it in the config file and the README).

I'm quite busy these time but am forecasting that in 2 weeks I should have more time for that.

[pauleveritt]

@vaab Thanks for the fast response. Yes, I was replying "in the case of maintaining a CHANGELOG file in the git files."

I am in no rush, so 2 weeks or more is no problem.

[simondrabble]

Hi @vaab , thanks for your prompt and well-thought out response. I had indeed been using gitchangelog to generate changelogs that were themselves checked in to git. However, I think for my case at least it is not necessary to have them committed, so I've updated my release process to account for this.