GitHub workflow changes

Bloke · 2016-09-10 13:03:19

IMPORTANT

Due to unforeseen issues that have surfaced with Git GUI clients, the proposed workflow here is messy. It’s fine from the command line, but GUI clients make it unnecessarily unwieldy. Please ignore this thread’s advice and try the amended workflow instead

Sorry for the hassle. Original message is preserved below.

—————————————————————————————————-

From this moment forward, we’re going to be adopting the GitFlow Workflow for Textpattern development. The changes aren’t revolutionary, but for those checking out bleeding edge code or submitting pull requests, the process is slightly different. The document explains things in detail, with examples, but I’ll just give you the gist here in specific Textpattern terms:

The master branch is now for stable releases only. We’ll never commit to this branch except at release time, or to bugfix the current stable release.
A dev branch has been created. This is where we’ll work on all code towards the next (major/minor) version. Currently, this’ll be 4.7.x.
When 4.7.0 is released, dev is merged into master, tagged and thus becomes ‘stable’. Then dev becomes the 4.8.x branch. And so forth.
All development, pull requests and cloning of development code takes place in feature branches based off dev. So if you’re working on a feature, ensure you’ve either:
- already checked out the dev branch first (git checkout dev) and then create a branch / PR for the feature (git checkout -b my-feature); or
- do it in one step git checkout -b my-feature dev.
When the feature is done, merge it back into dev with: git checkout dev, and then git merge my-feature. Delete your feature branch one you’re done with it: git branch -d my-feature.
If anyone spots a bug that needs to go into the stable branch line (so we need to do a 4.6.1, for example), please git checkout master first, create a hotfix branch/pull requests for the code and work on it there. When it’s done or raised, it’ll be merged into master directly and also merged forward into dev.
We can decide at any point to roll all such fixes made to master into a new point release. Once done, remember to git checkout dev again :-)
At release time, or for Release Candidates or betas, we’ll create a new branch called release-x.y.z based off dev. If we commit that to the central repo, that means it is feature-fixed. People can check out that release branch to test the release and submit PRs or bug fixes to that branch. This keeps things all nicely separated. Once a release is polished, it is merged into master and back into dev, tagged, then the release branch deleted as it has served its purpose.

One thing not mentioned in the doc above, is that if we want features / fixes to be packaged neatly instead of the commits getting lost among the timeline into which they’re merged, we can use the --no-ff (no fast-forward) option to the merge, which preserves the branch history. Although some say it’s harmful, this might be kind of desirable as it makes the bundles self-contained and easily extractable if we want to cherry pick or do some branch management. It does, however, add a few extra bits of noise to the commit history.

Hope this makes sense. Shout if it needs clarification or you have comments.

tl;dr:

master is for stable releases and bug fixes.
dev is for development.

Last edited by Bloke (2016-09-16 10:36:26)

gaekwad · 2016-09-10 15:48:50

Bravo.

philwareham · 2016-09-12 07:30:37

Hi Stef, just trying to get my head round this I understand branching off dev for new features and changes, which can be merged back into dev and potentially also merged into release branches. Got a couple of questions though:

For minor changes only needed for dev (not needed for a release branch) is it ok to commit directly to dev without having to branch every time?

Also, say we now want to do 4.6.1 work. So we branch off master and call it 4.6.1 branch yes? Do any commits in that (and also merge any done in a branch dev as mentioned above if they are required for both 4.6.1 and 4.7). When enough fixes are done in 4.6.1 merge that into master, delete branch and create a new one off master called 4.6.2?

Is that correct?

Bloke · 2016-09-12 10:11:44

philwareham wrote #301348:

For minor changes only needed for dev (not needed for a release branch) is it ok to commit directly to dev without having to branch every time?

Sure. Same as we used to just commit directly to master for tweaks. The only reason it’s best practice to use a branch is that sometimes a “minor change” has a habit of rolling into bigger things and by the time you realise this, you’ve made a bunch of commits or other people have made subsequent changes and they’re more difficult to unpick at merge time or to branch off cleanly to complete the feature.

But if you’re fairly certain it’s a small fix or you’re just tweaking the CSS or something, then a branch is overkill so, yeah, by all means commit directly to dev in that case.

Also, say we now want to do 4.6.1 work. So we branch off master and call it 4.6.1 branch yes?

We could, but I’d prefer not to because it’s an extra level of routine merging: we’d effectively have three concurrent timelines to manage. I’d prefer to use tags for releases, and only make a temporary branch when we’re approaching release. But I may be misguided. If anyone spots flaws in any of the following, by all means realign my thinking.

From my (possibly naive) perspective, anything on master goes towards the next stable branch. Whether that’s a point release or the next major.minor version is immaterial. The difference is where you branch from.

Any fixes to the master (a.k.a. stable) branch are done as hotfix feature branches and merged back in. But this is kind of where me and Gitflow diverge slightly (that’s an alternative link to the one in the OP). Gitflow states that any time a hotfix is applied, it’s merged back into master, is tagged and that becomes v4.6.1, v4.6.2, etc. Patching one bug doesn’t — in my mind at least — make a point release. Patching a few, does. Not least because we have other paraphernalia to do at release (update lang files, toggle flags, etc).

Some people use a third branch, maintenance, for interim releases but I think that’s too complicated, and overkill. I don’t see a problem with a “tainted” master branch, because people can always check out the latest stable release via the ‘Releases’ panel on GitHub, which has been tagged at some prior point on the master timeline. It’s what we’ve always done, and is easy to visualise.

So, my proposal is:

Features that go towards the next big (major.minor) version go on dev only.
Bugfixes are done as feature branches off master (or applied directly, if very minor: see above) and are merged back onto master but are not tagged until we want to issue a point release. These bugfixes are immediately merged into dev after they’ve been applied to master so they also appear in future major.minor releases. If they’ve been superseded by other changes in dev, fine. That’s up to the person merging to decide.
Maybe after a few bug fixes we decide to issue a point-release. At that time, we branch off master with a release-4.6.1 branch name (possibly with a -beta suffix if required), make any final tweaks on that branch (bump version numbers, pull in lang files, etc). Then when we’re happy, merge it into master and tag it with the point-release number, and pull the lot into dev so everything remains in sync. Delete the release-4.6.1 branch when done, as it’s served its purpose.
At major.minor release time, we branch off dev with a release-4.7.0 branch name [optional -beta / -rc suffix], prep it, tweak this branch if necessary, merging back into dev as required. Then when we’re happy, toggle the svn flag if it’s a final, merge the release branch into master and tag it with the full release number. Merge master to dev so the tag is pulled down. On the release branch, toggle the svn flag back if required and pull that change into dev so everything’s in sync. Delete the release-4.7.0 branch when done as it’s served its purpose. Then, increase the version number of files in dev to 4.8.0-dev.
Rinse and repeat.

This suits our proposed faster release cycle too: point releases are almost exclusively bug fixes from now on. New features and breaking changes go in major.minor versions.

Does that make sense?

It would be nice if we could somehow alter GitHub to show dev by default. Maybe we should set the default branch to make it easier for people to test bleeding edge code. Not sure if that’s worth it or has any repercussions.

Like I say, if there are any issues with the above, by all means let me know as I’m just cobbling together what I consider best practice from various web resources. There may be details I’ve overlooked, especially at merge stages.

If it’s conceptually easier for everyone to see three branches at all times, by all means we can adopt the ‘make release branch now and keep it in sync’ approach as you outlined above.

Bloke · 2016-09-12 10:43:27

Addendum:

For people wanting a stable release, grab one from the Releases channel or checkout a Tagged version.
For people pulling down code directly off a branch, if they git clone/git pull master they get the latest bleeding-edge version of the latest official release so they can test fixes and report back.
For people cloning/pulling dev they get the latest bleeding edge version of the next release.

Fewer branches = less confusion? Maybe… It does mean that after the next major.minor version has hit the master branch as a beta, no more bugfixes of the previous branch can be done unless we branch from an earlier point. Is that a disadvantage? I don’t know. One would like to think that by the time we get to beta of a new version, all known bugs from the previous version have been ironed out or superseded by new functionality. In an ideal world, at least…

philwareham · 2016-09-12 13:11:23

OK, all seems to make sense. Thanks!

I’ve changed the GitHub default branch to dev now, by the way.

Textpattern CMS

Textpattern CMS support forum

#1 2016-09-10 13:03:19

GitHub workflow changes

#2 2016-09-10 15:48:50

Re: GitHub workflow changes

#3 2016-09-12 07:30:37

Re: GitHub workflow changes

#4 2016-09-12 10:11:44

Re: GitHub workflow changes

philwareham wrote #301348:

#5 2016-09-12 10:43:27

Re: GitHub workflow changes

#6 2016-09-12 13:11:23

Re: GitHub workflow changes

Board footer