Fixup release instructions

[altendky]

Just whatever I catch while doing the releases.

Draft for:

• Tagging on a branch isn't great when you then squash-merge it (which is the default)
• Tagging on the branch also results in a double build Release 21.3.0 #332 (comment)
• The newsfragment creation and consumption to keep the build happy is silly. Should note this until Support explicitly selected 'change' and 'release' checks #309 (I think?) addresses this.

[codecov]

Codecov Report

Merging #330 (3de3f5f) into master (6b1527b) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #330   +/-   ##
=======================================
  Coverage   97.04%   97.04%           
=======================================
  Files          22       22           
  Lines        1321     1321           
  Branches      126      126           
=======================================
  Hits         1282     1282           
  Misses         20       20           
  Partials       19       19           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6b1527b...3de3f5f. Read the comment docs.

[adiroiban]

Any plan to continue working on this, or we can merge the current changes?

I did some minor changes to CONTRIBUTING.rst while doing the last release.

[altendky]

Go for it. Maybe the checklist in the OP would make sense to add as notes in the instructions until they are addressed?

[adiroiban]

The newsfragment creation and consumption to keep the build happy is silly.

I hope this will be fixed once #337 is merged.

---

Tagging on a branch isn't great when you then squash-merge it (which is the default)

I am not sure what is the issue here.

You tag the code that is released.
It's only for reference.

---

Tagging on the branch also results in a double build

I am not sure what is the issue there.

When you create a tag, we run all the checks to make sure we don't release something for which the tests are broken.

This is the strict release process.
I am fine with it.

I would also be fine, that when a tag is created, to only run the release task and don't re-run the tests.

The idea is that for a PR you see the test green and then you manually create the tag/release.

[altendky]

I find it a bit weird when a project's last release (or all of them for that matter) do not exist in the history of the main branch. Or you look at a release tag that fixed something and you want to see if that release is present in.. a given branch/PR etc and it doesn't show up because of the squash-rebase (they aren't merges, just rebases). Anyways, all processes have tradeoffs and the reduced traceability through git history is a cost of rebasing.

I'm not certain what I had in mind for the last one. Maybe it's about pushing a commit and a tag at the same time? The issue there is that both builds end up seeing the tag since we are checking if we are on a tag rather than checking if the build was triggered by a tag (I think...). So, they end up racing and the second one fails at some point. Though, it seems likely that we would tag an already-built commit instead so it's kind of an extra detail that is usually not a problem. I guess I realized it after actually triggering that scenario though. #332 (comment)

[adiroiban]

I find it a bit weird when a project's last release (or all of them for that matter) do not exist in the history of the main branch.

True. But but this is what you get when play god and rewrite the history :)

The changes were made into small commits, but with a squash you pretend that everything was a single big commit :)

I got used to that.

In practice, if a need to do a backport for an older release, I always create a new branch from tag and for me it's not really an issue.

So.. is this PR still a draft?

Can we merge it? Thanks!

[altendky]

[adiroiban]

Ready to land. Thanks!