Maintenance suggestions to lower bar for releasing patches

[hakonanes]

I've got some suggestions for simplifying and automating releases which I've used in kikuchipy for a couple months now and find to be very nice and efficient:

1. Change branch model from only master to master (preferably main) and develop which closely follow the Gitflow workflow branching model. Their specific roles in the kikuchipy repo: master receives two types of PRs, (1) single PRs with patches that should be released right away, ideally one PR per patch release, and (2) single PRs from develop when a minor/major release is to be made; develop receives two types of PRs, (1) the usual PRs of new functionality that should go into the next minor/major release, and (2) changes in master following any release, ensuring that everything in master is in develop as well.
2. Automatic creation of a release draft following a PR merge to master, provided that the release version has changed compared to the one available via PyPI. If the version has changed, the release draft is made with the correct title (orix 0.7.1), tag (v0.7.1) from the correct branch (master), and the release text has a fixed introduction (orix is an open-source Python library...) and the latest changes in the CHANGELOG.rst file. We can either publish this release as is, or make any modifications and then release.
3. Add a release guide explaining all necessary steps to make a release, both before, during and after.
4. Update contributing guide and PR template to reflect these changes.

Note that I had a discussion with @ericpre when making this change in kikuchipy.

Introducing an extra branch and specific branch roles adds some complications complexity to development, but I believe the benefits make it worth it.

[pc494]

This is an interesting changes, I have mixed feelings. I (personally) have certainly found manually writing the release notes very helpful as a way to organise what has been achieved and present it in a reasonable manner.

My main reticence is towards one patch per bug. Does the increased number of release actually lead to uptake? Would most people who needed bleeding edge code simply not build off develop?

Will continue to think.

[hakonanes]

I (personally) have certainly found manually writing the release notes very helpful as a way to organise what has been achieved and present it in a reasonable manner.

You can still do this, and I've done that for kikuchipy v0.5.1-0.5.3 0.5.2 myself. It's only a draft that's automatically created with changelog entries since last release and a standard intro, it can be edited as you normally would before being published, manually.

My main reticence is towards one patch per bug. Does the increased number of release actually lead to uptake? Would most people who needed bleeding edge code simply not build off develop?

These changes will hopefully reduce the time between when a bug is identified and when it is fixed. I find that the effort to fix a bug (instead of adding new stuff) is lowered, since I have a clear and simple path to releasing it immediately. The hassle with cherry-picking is removed.

I don't know if users use package versions with less bugs with this approach, but I would think so. I at least have a habit of updating packages every day, because I want the best performance (and to know whether something I've written breaks with updated dependencies).

In general I don't notify people of features before they are released, because things could change before that.

[pc494]

I've had a change of heart. I think (1), (3) and (4) are good. Would like some more information on how (2) ends up working in practice though.

[hakonanes]

How (2) works in the latest release 0.5.7 of kikuchipy:

1. Merging Fix EBSD orientation refinement on Windows kikuchipy#495, which contains a change in kikuchipy/release.py, onto main (master equivalent), triggers this workflow
2. The workflow calls this script which
   1. fetches the version from release.py from main (0.5.7)
   2. compares it to the one on PyPI (0.5.6) via the Python package outdated
   3. if branch and PyPI versions are different: creates a new file release_part_in_changelog.rst with a standard release header followed by a copy of relevant parts of the changelog since the previous release
3. Two outcomes:
   1. If branch and PyPI versions are the same the workflow ends and main lives on without being released.
   2. If the branch and PyPI versions are different, release_part_in_changelog.rst is converted to a Markdown file, and an annotated release draft with the Markdown file as body, the correct tag (v0.5.7), title (kikuchipy 0.5.7) and branch (main) is created by github-actions. This draft can be published as is, or modified and then released.

There are two manual post-release actions:

1. Merge main into develop via a third branch (because we don't want to merge develop into main before merging main into develop, which I find git requires): Main into develop after v0.5.7 kikuchipy#497
2. Update develop (mainly revert __version__ to 0.6.dev0): Updates to develop after v0.5.7 kikuchipy#498

[pc494]

Okay, this seems to avoid my main problem which is that you make lots of accidental release of 0.6.0dev etc - although you might create stray tags, that's possibly a price worth paying.

[hakonanes]

although you might create stray tags

The tag is created after a person presses "Publish draft". A new release draft is only made after __version__ on main and PyPI differ.

[pc494]

Mea Culpa, great.

[hakonanes]

No problem, I could have explained it better in the first place.

[hakonanes]

@harripj mentioned this in #299. I'm of course for this.

[hakonanes]

For example, we could have immediately released a patch release after merging each of the two issues marked as bugs in the 0.9 milestone (https://github.com/pyxem/orix/milestone/16?closed=1), by merging them directly with the main branch (as opposed to develop) and publishing the automatically created tagged release (given the version was updated to say 0.8.3 in one of the merged commits).

[pc494]

I'm happy for this to go ahead :)

[hakonanes]

Great, thanks for considering this, both!

[hakonanes]

I'll get it done after the full 0.9 release.

[hakonanes]

I plan to do these changes tomorrow. The currently open PRs have to rebase to develop (main only contain released commits or commits planned for imminent release) after the changes.

[hakonanes]

The changes suggested here have now been implemented. Thanks for helping out, both!