Git workflow improvement proposal

[jlirochon]

Proposal based on some good practices and some experience.

:shipit: Feel free to react / comment / add something / deny / remove me from the contributors...

• We should always reference a GitHub issue in our commit messages, ex:
  • "fixes number of online players #112"
  • "#112 oh yeah I finally fixed this fucking number of players"
• We should produce good commit messages, ex:
  • bad: "fixed"
  • good: "#42 added SuperCoolInterface to make things more decoupled"
• Only maintainers should have write access on master branch.
• Other developers should fix very small bug directly on develop branch.
• For anything more complicated, we should start a feature/some-feature-blah branch, and merge it into develop when finished and cleaned.
• We should start a release/some-release-blah branch for release polishing, while others can continue to work on develop branch.
• We should create pull requests, to let others detect issues, comment, or learn from the code. We can learn by reading pull-requests created by others.
• We should not commit things like "oops my fault again", "still not working", "trying one more time". We should try to clean up our history, and squash erroneous commits.

[DefinitlyEvil]

I have two questions:

• How to let a sub-branch auto-merge master branch commits?
• How to squash commits together? And thx for suggesting those ideas.

[ethsmith]

I like this idea

[jlirochon]

Which one ? lol

[ethsmith]

This all comes together as a big improvement idea so all of it

[DefinitlyEvil]

@jlirochon What about my question. ;)

[jlirochon]

1. There is a tool named git-flow, which add some commands to git, and manage this workflow automatically. For example when you start a release:
   • git flow release start 0.0.3 will create a release/0.0.3 branch from develop (always)
   • then you can push on this branch to fix last remaining bugs and do some polish
   • then you can git flow release finish 0.0.3, it will merge release/0.0.3 into master and develop, create a 0.0.3 tag, and delete the release/0.0.3 branch.
2. You can squash commits using git rebase command. You can change the orders of your commits too, or even split a commit into 2 commits.

[DefinitlyEvil]

@jlirochon

• release/0.0.3 branch will auto track master branch commits automatically?
• That's cool.

[jlirochon]

git-flow handles the following concepts:

• master branch always reflect the last stable version of the software
• develop is the developent branch, where the all the things explode
• feature/xxx branches always start from develop and are always merged into develop
• release/xxx branches always start from develop and are always merged into master AND develop AND they always create a tag
• hotfix/xxx branches (for security fixes or critical bugs) always start from master and are always merged into master AND develop AND they always create a tag

It's a quite common workflow

[jlirochon]

@DefinitlyEvil you mean develop branch, because master will never be updated until you release :)

And no, it won't track commits from develop. Release branches should be created when there is enough features and bugfixes on develop. You only create them to do last minute polishing, fix the last small bugs before releasing.

If you really want a fix from develop you can cherry-pick one commit or two using git cherry-pick f72f7c4 syntax. But you don't want to merge all commits from develop, because you are in the process of stabilising a release, not destroying it with random stuff :hankey:

[jlirochon]

And that's said, you can always do all that you want or need, it's just Git.

If you need to break the rules for some reason and you know what you are doing, you can do it.

[mastercoms]

Eh, I don't like git flow.

[jlirochon]

@mastercoms why ? Do you have other recommendation ?

[mastercoms]

Git flow isn't really the way you should use git. http://scottchacon.com/2011/08/31/github-flow.html

[jlirochon]

@mastercoms thank you, very interesting article !

I read the full thing, and I understand their points. Git flow is just a standardised way to use Git, there are millions of other possible workflows.

I think GitHub workflow (don't mix up with Git Flow) can apply to websites doing Continuous Deployment. Git Flow would slow them down. They explicitly says they have no concept of release, since they deploy all day (and night ?) long, that's why Git Flow can't suit their needs.

In our case, we can not push code on all dedicated servers on which Dragonet was installed by customers. Continuous Deployment doesn't apply to Dragonet (until we find a way to auto-update the code everywhere, and hot-swap it without losing connections to the MC clients). For now, we are still in a process of releasing versions, so Git Flow is still the standardized way to do it.

We could just craft a similar workflow, but git flow command has proven to be useful for people who forget to merge things back. It avoid mistakes like bugs fixed in version 0.0.3, but oops they're back in 0.0.4, because someone forgot to merge a certain commit on a specific branch at some point.

I retain their argument of people only using Git through a graphical interface. I will be happy to help people who want to improve their Git skills. And I would say that not all developers need to use Git Flow. Most of time we are just working on a branch as usual, and only the maintainers have to manage releases and hotfixes.

[DefinitlyEvil]

@jlirochon Wow, update without restart will be crazy! :O Even Bukkit can't achieve it yet.

[mastercoms]

Well, I would see GitHub Flow working in a similar fashion for Dragonet. We can fix small bugs and tweak things on master, while forking master for big changes/new features. Once they are done, we merge them back to master. This is GitHub Flow.

The thing that would be different is that once we have met our milestones in terms of bug fixes/features for that version, we move a pre-created tag for the next version out of pre-release, and finalize it. Then we create a new tag in pre-release for the next version, and continue development.

I feel like git flow over complicates things. Since all versions would share the same branch, it would not be possible to forget to merge things for a later version.

[jlirochon]

Ok, Git Flow uses develop for development branch, but it's just a branch name, and it's just a convention. If I take your proposal and replace master by develop for small bugs and tweaks, it's all the same. Git Flow is just a conventional way of doing things.

For the release part, yes your proposal is much simpler, you just tag a commit on master at some point and declare this will be a release. All versions share the same branch, and there is no merge.

In this configuration, the problem, if any, is that you miss the opportunity of releasing a stable thing. Everyone has access to master, so il real world when working on a team you have some options:

1. just tag some commit that looks not so bad, and declare this is your release (your proposal)
2. tell everyone not to push on master, because you are creating a release, and you don't want crap to be pushed during this process (tends to annoy and slow down the team)
3. create a release branch, do whatever you want on it, then release it (Git Flow)

For now, Dragonet has no stable release, so just choosing an arbitrary commit can do the trick. But in the future, we may not release a new version before having tested it on some servers during a couple of days, and fixed some remaining bugs.

Actually, compared to just tagging a commit, Git Flow would introduce the following overhead for the releaser:

1. git flow release start 0.0.4
2. bump to new version in DragonetVersioning and some other files
3. git flow release finish 0.0.4
4. git push origin master:master --tag
5. git push origin develop:develop

Step 2 will grow when releases will need more stability. It's up to the releaser to decide if it's worth trying git flow or not.

At the end, I still would like to have a develop branch, and a master branch where only releasers can commit

[mastercoms]

As soon as you commit the last commit for 0.0.3, for example, you make the final 0.0.3 tag, so there is no need to tell anyone to stop committing. If you want to test, just make 0.0.3 labeled as a pre-release. After testing, label it as a release. Then people can download this stable version from the tag.

Anyway, I think @DefinitlyEvil should decide.

[jlirochon]

@mastercoms I don't agree with your last comment, but anyway, let's defer the release thing until we feel the need for improvement.

Can we adopt other proposals ?

• useful commit messages (ie not just "fixed lol")
• adding the issue number at the end of the commit message like "fixed player spawning into the ground #123" (having a # on line start cause git to consider it as a comment)
• on voluntary basis, rewriting our local history before we push, to avoid polluting the history with "oops I did it again" commits. I know this one is a bit tricky, and I will be happy to help anyone willing to push cleaner commits.

[mastercoms]

I agree that with all of those.