Release planning (19.9.0rc1, 19.9.0, and 21.3.0)

[altendky]

19.9.0rc1 has been release to PyPI but was not tagged or merged back to master. No 19.9.0 release steps have been taken yet. Subsequent develop is (maybe?) ready for a 21.1.0 21.3.0 release. So, there are some various existing bits to cleanup and new bits to create.

101d60e seems to be the commit released as https://pypi.org/project/towncrier/19.9.0rc1/ and doesn't have either the 19.9.0-rc1 release notes (fixed in 280e5b3) nor an (empty) 19.9.0 release notes entry (should be added if releasing 19.9.0). It also has a formatting error in the readme fixed in 1f396ea. Both linked commits are in the hawkowl/release-19.09 branch but are after the seemingly 19.9.0-rc1 released commit 101d60e. A 19.9.0 release ought to include all of those plus an empty release notes section for 19.9.0 itself.

Here are my proposed actions:

• Tag 101d60e as 19.9.0rc1 to give reference to anyone looking for what https://pypi.org/project/towncrier/19.9.0rc1/ is.
• Close (Merge in 19.09-rc1 #310) since it has a catch up merge of master into hawkowl/release-19.09 so it is not fit for any release.
• Document the release process (Release instructions #317)
• Implement any release automation associated with the new process (twisted-alike (so similar) automatic publishing on gha #315)
• Fix release instructions to use incremental to define the textual form of the version (use incremental to canonicalize versions for release #329)
• Create a new PR (Release 19.9.0 #331) for a 19.9.0 release PR based on 101d60e 280e5b3bbcd84812b6a4a5f159a8194db757b309(present latest on hawkowl/release-19.09)
  • Bump version to 19.9.0 (no rc1)
  • Build an empty 19.9.0 release notes section (by running towncrier, of course, to be clear)
  • Get a review on the final 19.9.0 release commit (9f6c426 in Release 19.9.0 #331)
  • Tag that commit as 19.9.0
  • (no PyPI release yet, see below at 21.3.0 release point)
  • Merge this release PR into master
• Create a new release PR for 21.3.0 from master including 'all recent development' and the merged 19.9.0 release
  • Bump version to 21.3.0
  • Build the 21.3.0 release notes section
  • Get a review on the final 21.3.0 release commit
  • Tag that commit as 21.3.0
  • Now that both 19.9.0 and 21.3.0 are ready for PyPI, build and upload both
    • Perhaps this can avoid confusion from devs suddenly getting an effectively 15 month old release showing up in their workflow.
    • Hopefully we don't find problems with 19.9.0 now :|
  • Merge this release PR into master

Ok, so what bits did I forget or did I get wrong?

[altendky]

I would still be curious though what the importance of a 19.9.0 release is.

[altendky]

Or, perhaps you did intend for all the development from 2020 to go into a 19.9.0 release? Though that seems like a confusing thing to do, to me.

[altendky]

Apparently I didn't write @adiroiban at any point... :[ so there is the ping.

[adiroiban]

You plan is perfect :)

Very well explained. I agree with everything.

---

I guess that we need to define the release process.

My suggestion is to use something similar to twisted.
Make sure we include a release candidate as part release process so that we can also validate this use case.

So the release process could be like this, documented in CONTRIUTING.rst:

For the pre-release / release candidate:

• When a release is done create a new release dedicated branch in the main repo (Not in a fork)
• Name the branch release-VERSION where VERSION is replaced by the final version to be released
• Update the version in the branch to target version and rc1
• Create the release notes using towncrier itself
• Commit the change.
• Ask for a review. Reply to review.
• Once the PR is approved after a review, tag the changes as VERSIONrc1 to be PEP complaint.
• Push the changes and the tag.
• GitHub action should trigger a workflow that will publish the wheel on PyPI.
• Let people know of the pre-release and ask them to give a try

For the final release:

• If issues were found during the pre-release, those changes should be fixed and merged in master
• Either merge master in the release branch, or cheery-pick the fixed from master.
• Using the same branch update the version to the final version.
• Run towncrier again.
• Commit the changes as for a new review, reply to review.
• Once approved, tag the release with VERSION.
• Push the changes.
• Create a release in GitHub Release GUI and use that GUI to create the tag.
• GitHub actions will create and publish the wheel

---

I think that is enough to have just a RC1 and after RC1 to always do the final release.
The RC1 is more about exercising towncrier capabilities to support a release-candidate / pre-release process.

[adiroiban]

I think that we should create as many branches in the main repo as possible.
In this way we don't need to tick the extra option to give write access to external people.
Also, with a branch in the main repo, when you close a PR you have the button to delete the branch...so is should be easier to do cleanup.

But this is a minor comment.

[altendky]

I added a couple steps before the 19.9.0 release to document the release process and setup the automation.

• Your notes say to "Push the changes and the tag." after the PR approval and tagging. I would think that there would be no changes and that would be "Push the tag."
• For post-rc fixes I would have defaulted to having the PRs target the release branch. And if they make it into master then cherry pick to another branch that PRs against the release branch. I guess my thinking is that we already initiated a release thinking we didn't have problematic bugs and were wrong, so let's not shortcut anything in the midst of the rc/release process and instead allow full normal reviews of changes exactly as they affect the release itself.
• When I think of RCs my head always thinks about the final release being exactly the last RC with no changes but version. This is likely excessive, but maybe writing it will help get it out of my head.
• Why doesn't the RC get the same "GitHub Release GUI" treatment as a final release?
• For the final release you wrote "tag the release with VERSION" and later "use that GUI to create the tag." which sounds like double tagging.
• Humm... should there be some post-release change to the version to indicate that future commits aren't the release version? Trio, for example, adds +dev. Though with towncrier using incremental, I don't know offhand the options.

---

Regarding the minor comment...

The author always has the button to delete their branch. If it is in the main repo then the setting to autodelete branches works. But, I don't see how that's anyone's business but the PR/branch author's. For the extra write access option are you referring to the PR author allowing the target repository's owners being able to modify the PR? I though that was on by default so not really a concern. I personally like using the same workflow regardless of my write access to a repository (unless it is literally my repository in my personal account, I guess) and even consider GitHub's inability to create a branch in my fork via the web UI when editing a file to be an annoying oversight.

In short, I'm not really clear exactly what activity is troublesome for you with PRs from forks.

[altendky]

Should we start prefixing release tags with v or just identify off of starting with a digit?

[adiroiban]

Should we start prefixing release tags with v or just identify off of starting with a digit?
I think a digit is good enough. No need to prefix v

For towncrier I don't think of any usage for tags, other than tagging releases.

---

Also, for towncrier, I think that we should keep the release process as simple as possible.

So if we release 20.1.0 and later found a bug, the next release will be from "master".

If master contains only bugfixed and the release is in the same month, the next release will be 20.1.1 ... otherwise 20.2.0

I would not bother with old release branches and backporting fixes from master to the release branch.

You would do that for a big product.... but not for towncrier which is a small library with limited dev resources.

Regarding my release notes. Your comment are correct. There are errors in my list.

I think is best to have a separate PR in which CONTRIBUTING is updated with what you think is best for towncrier.

Thanks!

[altendky]

Yes, I was going to start a separate contributing PR but hadn't gotten there yet. My comments about the release branch etc wasn't regarding long term or even just post-release fixes. Only post-rc fixes to be included in that release.

[altendky]

Release email draft moved to #332 (comment).