Document the release process

[andrewnicols]

@stronk7 This is one for you. I'm guessing:

• tag
• draft release

Are there any other steps to perform?

[kabalin]

May be use GHA for automated release on tag?

[stronk7]

Right now, for moodle-cs(undocumented) what I do is:

1. Create the "prepare" commit, where changelog is triple-reviewed and prepared. Push.
2. Create a draft release @ github (with the changelog section pasted manually). And with a new tag candidate.
3. Wait for GHA to end
4. Publish the draft release (that creates the tag, from the candidate one) and so on.

Instead, for moodle-plugin-ci (documented) what we do is:

1. Create the "prepare commit", where changelog (and the cli version) are triple-reviewed and prepared. Push
2. Wait for GHA to end.
3. Tag locally and push the tag.
4. Bump, everything happens automatically (the release happens, the correct changelog section is added to release notes and so on).

Personally, I prefer the way that we do it @ moodle-plugin-ci so my personal proposal is to:

1. Apply the same release process to moodle-cs.
2. Document the resease process similarly too (/docs new directory is ok?).

How does that sound?

PS: Special comment about the strong "triple-reviewed" expressions above. Once a release has happened we shouldn't be editing it ever, coz it leads to dupe notifications here and there, hence we need to ensure as much as possible that the changelogs are 100% correct (quantity and quality).

[kabalin]

Personally, I prefer the way that we do it @ moodle-plugin-ci so my personal proposal is to

+1

~May be use it as chance to review automated release process too? We created one in moodle-plugin-ci some time ago, since that there some new features in GH, such as release notes template, and alternative actions such as action-gh-release (has generate_release_notes param which uses the former template).~

NM, I did not notice you reviewed it recently, yeah CHANGELOG extraction seems better.

[stronk7]

May be use it as chance to review automated release process too? ...

Yeah, we use other actions for extracting (link) and releasing (link), but it's pretty automated (and working ok) with them.

So the idea is to apply here for the same release.yml workflow (surely simpler one) and done (plus document it, of course).

Ciao :-)

[andrewnicols]

I like the idea of automating this too.

Perhaps we can combine it with switching changelog generation to something like changie so that each change has a changekog entry and the release process generates the changelog, and performs the tag, and the release.

[stronk7]

Perhaps we can combine it with switching changelog generation to something like changie...

I personally feel it's sort of "too much" to use changie for these tools, but I don't oppose if we want to experiment with it. After all, it requires to go adding changie new chunks of information to it (+commit them), pretty similar to what we already do adding those same chunks to the current CHANGELOG (+commit them). Other than that, I'm ok, so far.

Ciao :-)

[stronk7]

For reference, I've quick tried this and seems to be working (note I've had to change the "extraction" action because the "v" versions that we are using here in the changelog aren't strictly "semantic versioning", it seems that the "v" shouldn't be included there, no matter the tag has them.

Anyway:

• Code: https://github.com/moodlehq/moodle-cs/compare/main...stronk7:easier_releases
• Example release (generated on pushing the v3.4.7 tag upstream): https://github.com/stronk7/moodle-cs/releases/tag/v3.4.7

TODO: Create the doco, if we like this.

Ciao :-)

[andrewnicols]

I like this!

[stronk7]

I've created #152 with the initial proposal. It 99% mimics what we have @ moodle-plugin-ci. See you in the PR!