Enhancement: a template for GitHub releases

[nedbat]

I'd like to add some text to the top of the release, like:

To install this, use `python -m pip {project}=={version}.
The PyPI page is here: https://pypi.org/project/{project}/{version}.

This could be a template applied to the markdown generated from the changelog.

[kevinmatthes]

I have an idea for the implementation of this feature but I am not quite how to test whether it works as it should. I would like to present you the idea anyway in order to discuss whether this suggestion would fit the requirements of the new feature requested. In the following, the template file will be named "preamble" as it is some text preceding the actual content.

First of all, the preamble should be a new option to configure. That way, users are free to choose to use a local preamble or, for instance, another one stored centrally in one of their submodules. I thought of something like

# src/scriv/config.py, ll. 197
    # The default preamble text to insert.
    preamble = attr.ib(
        type=str,
        default="preamble.${config:format}",
        metadata={
            "doc": """\
                This is the file storing the default text to be inserted before
                the actual changelog entries.
                """,
        }
    )

for the implementation of the new option. Users could then alter the path as required.

I would like to suggest to add the content of the preamble to the changelog, as well, since the installation instructions might change with every release. For Python projects, this can happen because the respective project is continued in another repository, see bump2version for an example; for any other projects, there might be major changes to the build routine.

Adding the preamble to the changelog, at first, would also simplify local tests, in my opinion. The configuration option would be required in both cases and moving the (invocation of the) business logic to another source file is a simple change once it works appropriately. Since the release logic reads out the changelog, the preamble would be added in each case.

In general, @nedbat, what do you think about this suggestion?

References

• Verkerk, C., & The bump2version Community. (2020). bump2version (Version 1.0.2-dev) [Computer software]. https://github.com/c4urself/bump2version

[nedbat]

I like the idea of a template for releases, and possibly also for the changelog as a whole. But I would make two changes to your design:

1. I would make the template be a full template, not a preamble. The generated content (that is, today's content) would be provided as a variable. That way, the template could provide text before and after the content. In essence, the default release template would be simply:

{{ content }}

2. If we have a template for the changelog, it should be separate from the template for releases. They have different audiences and needs. I haven't thought of what I would use a changelog template for, so I'm less sure that it's a useful thing.

[regisb]

I'm also interested in having a template for GitHub release descriptions. For the record, this is how I generate GitHub release descriptions in Tutor: https://github.com/overhangio/tutor/blob/b903c69fac95e797532288d4e6f60530faf1db94/Makefile#L93.

And here is the GitHub description template (really just a preamble): https://raw.githubusercontent.com/overhangio/tutor/master/docs/_release_description.md

This little song-and-dance is a little tricky. For instance, it requires that I manually copy-paste the changelog to the commit message and title. I could avoid that with a GitHub description template. Alternatively, this workflow could be simplified if I just had a scriv print-changelog command.

[nedbat]

@regisb what do you want scriv print-changelog to do? How would it help with the flow?

[regisb]

@regisb what do you want scriv print-changelog to do? How would it help with the flow?

Currently, I create GitHub releases in a GitHub action with the gh release create command. (workflow source)

I do not use scriv github-release because I want a custom release description.

The solution I found to generate the GitHub release description is to store the release changelog in the release git message. (with copy-paste, see release instructions). Then, I output the full GitHub description to stdout by running (source):

sed "s/TUTOR_VERSION/v15.0.1/g" docs/_release_description.md
git log -1 --pretty=format:%b

I could avoid storing the changelog in the git message if I had a scriv print-changelog command.

I am aware that this feature is only tangentially related to the issue at hand here. The reason that I am mentioning it is that it should (I think) be a quick win that is simpler to implement than the GitHub release templating.

[nedbat]

I've implemented the release templating in commit 3c55b26.

[nedbat]

This is now released as part of scriv 1.1.0.