Shaarli: Release process / Git workflow

[ArthurHoaro]

Hi!

When I had to release a major bug for v0.8.2, I came up quickly with a release process which I've explained here. Though, I didn't really think it through, and @alexisju made a good proposition.

Instead of having a v0.x branch, we create a release branch and any release should be made from this branch, either by:

• cherry-pick a commit from master (bugfix)
• git merge master (full release)

This would avoid any confusion of knowing what's been released or not.

I created this issue to get your opinion on this, since we now have the time to think it through.

[virtualtam]

Here's a pretty standard release workflow:

• develop on master
• use release branches on which tags are created, that mostly receive hotfixes:
  
  
  
  • branch: v1.2
  
  
  • tags: v1.2.0, v1.2.1, etc.
  
  

Usage:

• release branches are decorrelated from the main development branch(es)
• if using Git, possibility to checkout a given branch and update it when hotfixes are published
• upgrading means switching branches
• tags (releases) are spread across multiple branches

A similar alternative is to always develop on a named branch, and merge it into master when a tag is created:

• develop on v0.9
  
  
  
  • when v0.9.0 is released, merge the v0.9 branch into master
  
  
  • when v0.9.1 is released, merge the v0.9 branch into master
  
  
  • ...
  
  
• freeze development on the v0.9 branch
• develop on v0.10
  
  
  
  • ...
  
  
• oh noes! there's an issue with v0.9.3!
  
  
  
  • commit a hotfix on v0.9
  
  
  • tag as v0.9.4
  
  
  • cherry-pick the hotfix to v0.10 (more generally: cherry-pick the hotfix to all impacted branches)
  
  

Instead of having a v0.x branch, we create a release branch and any release should be made from this branch

This would only worsen the current situation, as having a single release branch would:

• prevent from releasing hotfixes on past releases (i.e. fix something on v0.5.x)
• lead to a wild diverging branch (with respect to the master branch)

[alexisju]

Currently, latest builds are made from v.8.0 _and/or_ from master.

As template maintainer, this situation is not the most comfortable. It is not always easy to follow which PR is committed into the master and eventually backported in latest zip build.

I would like to work on a "reliable" branch.

I think also that for non developers, a permanent release branch could make easier install and update from git (without to have to change branch or following technical development of Shaarli).

[virtualtam]

As a maintainer, I'd like to keep the release process as simple as possible; we try to make regular announcements on #353 when impacting PRs are about to be integrated, and our issue tagging is quite consistent.

I think also that for non developers, a permanent release branch could make easier install and update from git (without to have to change branch or following technical development of Shaarli).

Non-technical users, or people who don't want to get involved in Shaarli development, should rather use our release archives, where upgrading is a matter of drag-n-dropping new resources (scripts, themes, 3rd-party, etc)

Git is all about branching and managing revisions in an elegant way, I do not see the purpose of thrashing a branch on which we would only cherry-pick or merge stuff from active branches, for the sole sake of providing a sort-of-linear commit history, that would essentially diverge from master...

[ArthurHoaro]

A similar alternative is to always develop on a named branch, and merge it into master when a tag is created

I want to keep development on master because it's a common usage on Github for pull requests.

This would only worsen the current situation, as having a single release branch would:

• prevent from releasing hotfixes on past releases (i.e. fix something on v0.5.x)
• lead to a wild diverging branch (with respect to the master branch)

Good point. So I was on the right way with the v0.8 branch, except we should expand its usage, as you said:

• commit everything to the master branch
• create a v0.x new branch for every major version
• to release:
  
  
  
  • either cherry-pick or merge the master branch to the v0.x
  
  
  • always make the tag/release v0.x.y from the v0.x branch.
  
  

This would allow @alexisju to have releases coming from only one branch (or multiple if we really need to backport a commit to a previous major version, but that's not likely to happen).

Did I understand correctly?

[virtualtam]

Yep, that's the spirit!

Additionally, releases can be distinguished from dev versions using shaarli_version.php:

• released version: vX.Y.Z
• master: master, next or vX-next

This would allow theme devs to focus on supporting "official" releases, and mark support for the development Shaarli versions as experimental / YMMV

[virtualtam]

I'd like to address this topic before starting the 0.9.x release cycle, here is a proposition summing up previous discussions:

• master development branch:
  
  
  
  • where cool stuff happens ;-)
  
  
  • this should be identified with a special release code, e.g. dev or next
  
  
  • should not be used for version checks and update notifications (related: #778)
  
  
• release branches, e.g. v0.8:
  
  
  
  • can be used for update checks
  
  
  • only receive hotfixes and minor patches
  
  
  • can be used by template/theme maintainers as a reliable base
  
  
• latest branch:
  
  
  
  • points to the latest & greatest release
  
  
• stable branch:
  
  
  
  • points to a rock-solid release
  
  
  • might not be needed with proper release branch usage
  
  

EDITS:

• 2017-03-11: add latest branch

[ArthurHoaro]

I have a suggestion which will add another step to the release process but would prevent future errors.
I'd like to add a latest branch who would points to the latest release tag.

Explanation: if we use a dev version in the master branch, the checkUpdate method must point to the latest v0.x branch to get the version, which means that we need to update the branch list and update the user setting for every major version. With a latest branch, we don't need any change, except updating the branch at every new release.

[virtualtam]

+1 for a latest branch, I'll update my post accordingly

[ArthurHoaro]

Nice. I've updated https://github.com/shaarli/Shaarli/wiki/Versioning-and-Branches and pushed the new branch.

https://github.com/shaarli/Shaarli/wiki/Release-Shaarli will have to updated when we'll release v0.9.0.

[ArthurHoaro]

Wiki updated!

Note that merging the releases into stable and latest branches can bring conflict which aren't easy to fix. Hopefully my merges are clean, I relied on UT.