Include date of stop revision in generated output

[lagru]

As recommended in https://keepachangelog.com/en/1.0.0/, release notes or changelogs should contain a date in some form. It's easy enough to include if we settle on what should be the truth. I tend to think it should be the timestamp of the last given revision (stop_rev). This should lead to a correct release date for most cases.

[jarrodmillman]

I would think the date should be the release date (i.e., the date the tag was made). That could be difficult to get right since the changelist is run before tag is made.

Maybe changelist could be extended to handle making the tag as well. If we do that, then it could insert the date at the same. So replace

- Commit changes:

      git add pyproject.toml CHANGELOG.md
      git commit -m "Designate ${VERSION} release"

- Tag the release in git:

      git tag -s v${VERSION} -m "signed ${VERSION} tag"

  If you do not have a gpg key, use -u instead; it is important for
  Debian packaging that the tags are annotated

with

- Commit and tag changes:

      git add pyproject.toml ${CHANGELOG}
      changelist tag ${VERSION} ${CHANGELOG}

where

      changelist tag ${VERSION} ${CHANGELOG}

does something like

      git commit -m "Designate ${VERSION} release"
      # replace a comment in the ${CHANGELOG} with the current date
      git tag -s v${VERSION} -m "signed ${VERSION} tag"

[lagru]

Hmm, the date / tag thing is indeed more tricky than I thought.

I don't think we should expand the scope to creating tags. Right now I like that changelist works entirely on the remote repository with read-access only. Tagging would require to break with that. How about the following solution instead?

• Default to the date of stop_rev.
• Optional --date DATE option (just like --version) that overrides the date of stop_rev.

[jarrodmillman]

It is hard to predict when you will make a release. So I don't think there is much need for a --date flag. I can just add a note to the release process for projects I am using this for reminding me to manually fix the date when I make the release tag.

Maybe a better solution would be to add a --date flag that would use the date of stop_rev to add a date to the release notes. And if you don't use the flag, then you don't get any date inserted. That would certainly make things easier for me as I could just not include the date.

[stefanv]

For now, can we just use the current date? It'd be nice to have some date in the default template.

[bsipocz]

For what it worth, I always use the date of releasing. One will never find a good date for when development stops as last minute bugfixes will make it into the release, but the date of tagging can be well established --> finalize changelog --> make the tag.

If there are problems with the tag and the actual release being uploaded then one can still amend the changelog as necessary.

[stefanv]

Also, a more general solution to this may be to allow templating of certain values. E.g.:

template:
  title: `MyProject {release-name} — {date}`

Maybe the template could be a jinja file that we can customize 🤷 Dunno if that's feasible, just a thought.