Refactor release process in order to include changelog in release files

[chrysle]

• I have added a news fragment under changelog.d/ (if the patch affects the end users)

Summary of changes

This ought to correctly include the changelog in the docs on release, after PR merge.

Test plan

Tested by running

# command(s) to exercise these changes

[Gitznik]

I think this is an okay quick fix (potentially for the next release so we're not blocked by this?).

What I don't like about this is that the release artifacts in github releases would not contain the updated changelog. Not a huge deal I guess, but feels wrong.

[chrysle]

What I don't like about this is that the release artifacts in github releases would not contain the updated changelog. Not a huge deal I guess, but feels wrong.

I understand. What alternative do you suggest? My idea would be to transfer the release-related jobs from the tests workflow to a new release workflow with a workflow_dispatch event, then configuring the "Bump changelog on release" job to actually create the release, causing the other jobs to run. We would end up running that workflow manually to release.

I could rework the PR towards that, WDYT?

[Gitznik]

I understand. What alternative do you suggest? My idea would be to transfer the release-related jobs from the tests workflow to a new release workflow with a workflow_dispatch event, then configuring the "Bump changelog on release" job to actually create the release, causing the other jobs to run. We would end up running that workflow manually to release.

I could rework the PR towards that, WDYT?

Yes, that would be my suggestion as well. Should lead to the cleanest result overall. Just mentioning that @gaborbernat mentioned that this project tries to avoid this kind of workflow, but I don't see a good alternative.

[gaborbernat]

Where would you specify the version to release in a workflow_dispatch?

[Gitznik]

Where would you specify the version to release in a workflow_dispatch?

From one of our deployment workflows at work:

[gaborbernat]

Works for me 👍 remember to update https://github.com/pypa/pipx/blob/main/CONTRIBUTING.md#releasing-new-pipx-versions

[chrysle]

There is one complication which requires a bit more discussion. If we want to stick with opening a pull request every release to update the changelog, how can the same workflow be configured to create a GH release after that pull request is merged?

[Gitznik]

There is one complication which requires a bit more discussion. If we want to stick with opening a pull request every release to update the changelog, how can the same workflow be configured to create a GH release after that pull request is merged?

I think release-please does it by giving the changelog PR a specific label and watching for that label for creating the release.

[Gitznik]

Will you work on this soon @chrysle? If not I'd suggest we create a release soon with the current setup. There's a pretty good amount of bug fixes and new features to be released now.

If we do one with the current setup, I can manually create a PR updating the docs, so they show up correctly in the docs after the release?

[chrysle]

There's a pretty good amount of bug fixes and new features to be released now.

Agreed. I just discovered that release-please unfortunately won't help in our case, as it doesn't allow for disabling the automatic changelog generation (yet, see googleapis/release-please#2007). Thus I guess I'm going to extract the bump-changelog job into a separate workflow.

[chrysle]

Updated. See the result in chrysle@fff3448.

[Gitznik]

While your current solution works, what about giving this changelog PR a specific label and run the release via pipeline when a PR with that label is merged?

Label is a direct part of the pull_request object when using the pull_request trigger, and the version to release we can extract from the PR title, which is also in the pull_request object.

Removes one manual step from the pipeline.

[chrysle]

I'll look into it, it could take a little bit of time, though.

[chrysle]

This isn't quite that easy, as it turns out.. After trial and error for a while I finally managed to get my workflow to trigger on
a merged pull request with a specific label (see the successful run), but just as it creates the release, the tests workflow is already running on the push event, and the pushing of the release tag is somehow swallowed, because of which the CD isn't triggered. Any suggestions?

[chrysle]

@henryiii May I ask for some advice? The current state is at https://github.com/chrysle/pipx/tree/test-cd.

[chrysle]

@henryiii Pinging you on this as requested.

[Gitznik]

This isn't quite that easy, as it turns out.. After trial and error for a while I finally managed to get my workflow to trigger on a merged pull request with a specific label (see the successful run), but just as it creates the release, the tests workflow is already running on the push event, and the pushing of the release tag is somehow swallowed, because of which the CD isn't triggered. Any suggestions?

Just seeing this now. That sounds quite tricky indeed. As far as I'm concerned, unless someone that is really into github workflows wants to pick this up, I'm fine with having a 2 step release. Manually creating the release after merging the changelog changes is easy to document and not that difficult or prone to error.

I'm sure your time is better spent somewhere else than this ;) Sorry I sent you on this goose hunt.

[huxuan]

IIUC, those release related jobs/steps should belong to a different workflow, which maybe release.yml. The workflow is triggerred when a pull request merged with specific label. It might be something like

name: Release

on:
  pull_request:
    types: [closed]

jobs:
  create-release:
    if: >-
        github.event_name == 'pull_request'
        && github.event.pull_request.merged == true
        && github.event.pull_request.labels.name == 'release-version'
    steps:
      - ...
      - ...

[chrysle]

IIUC, those release related jobs/steps should belong to a different workflow, which maybe release.yml

Yup, you're seeing an outdated version here, actual work happened at https://github.com/chrysle/pipx/tree/test-cd. But your comment inspired me to attempt moving all the release-related jobs into this workflow, and I finally managed, although I went half crazy (this is the last time I've done anything with GH Actions here, rest assured). Here the successful run and the release it created. If you think that's all in order, I'll merge the development branch; otherwise, I'll give up.

[huxuan]

If you think that's all in order, I'll merge the development branch

IMO, it looks pretty good.

Previously, I just use a tag in semver to trigger the release process. This two steps release process is quite a good idea. I may also apply it in my personal projects. :-)

[Gitznik]

Great stuff

[huxuan]

Just realize some concern about concurrency.

[chrysle]

Thanks for correcting my oversight! Updated.

[huxuan]

Great job!