This is an old revision of the document!
Github Best Practices
This page is probably a bit biased towards my (Traumflugs) personal preferences. As so often, there are many ways to solve a task. Still I think I have good reasons for the strategies shown here, and I'll elaborate on this reasoning.
Tooling
Gitk basic usage.
Git is a very powerful and flexible tool and similar to programming languages, it requires the command line to take advantage of this flexibility. There are many Git related GUI tools out there and all I've seen so far pretty much cripple Git into a Time-Machine-like dumpyard.
Tooling needed:
- Git. Obviously. Ubuntu came with version 2.17.1 when this page was created.
- Gitk. Part of the official Git distribution. A simple and efficient repository browser giving a good overview. Without this overview it's often hard to understand what's going on. Command line parameters don't matter, one starts it with
gitk –all&(two dashes) in the repository to browse.
Avoid broken Code on the Main Branch
We all make mistakes. Typos, incompatibilities with other PHP versions, such stuff. That's why thirty bees core repository invokes Travis CI on every branch tip pushed to the repository.
However, such code shouldn't land on one of the main branches. Because it makes crawling or bisecting the history of the repository much harder. It also risks picking up the failure again when cherry-picking this particular commit to another branch. On main branches, every single commit should work flawlessly. Which isn't hard to achieve when following strategies here.
A “topic branch” is any branch in a Git repository not being the main branch. This is, any branch other than 1.0.x and 1.1.x as of this writing. Topic branches can get created and removed as needed.
Test on a Topic Branch
The most simple way to avoid broken code entering main branches is to test on topic branches. Put your commits there, then push them. Such branches get tested the exactly same way as the main branch. What works on a topic branch works on the main branch as well.
As one can see, I simply use a topic branch markus for everyday work:
Topic branch created.
Then this branch gets pushed, which triggers a Travis CI run:
git push thirtybees markus
Topic branch pushed.
At this point, or a few minutes later, one should visit the repository in the web browser on Github to find out how well these Travis CI tests run.
After Successful Test
After Travis CI tested found no flaws, main branch gets forwarded to the topic branch:
git checkout 1.0.x git rebase --autostash markus
Main branch rebased.
Then push the new main branch:
git push thirtybees 1.0.x
Main branch rebased and pushed.
Tip of branch 1.0.x is now the exactly same as the tip of branch markus, they share the same Git hash. Due to a flaw in Travis CI it'll get tested again, which doesn't matter. Result of the second run will be the same as that of the first one.
Task done. Don't forget to switch back to the topic branch before picking up the next task:
git checkout markus
On Test Failure
Test failures are no big deal as long as they happen on a topic branch. Now two things should happen:
- Fix the flaw on the topic branch.
- Edit commit(s) in place.
The latter is essential, else the broken commit will stay broken, with all the drawbacks described above.
Editing the Last Commit
Editing a commit in place is trivial in case it's the last commit. One does code fixes as usual, then commit the same way as when creating a new commit, but add the –amend (two dashes) parameter. Like:
git commit --amend
This brings up the commit editor as usual, one proceeds as usual.
With this done, the repository looks like this:
Topic branch after amending a commit.
Local and remote Git hashes are no longer the same. To nevertheless push this branch, one needs the additional -f flag:
git push -f thirtybees markus
That's all. Travis CI will run again on this branch. Depending on test results, repeat this section until tests succeed, then continue in section After Successful Test.
Editing an Earlier Commit
Editing a commit which is not the last one requires interactive rebasing. That's a bit more complicated and also a very powerful tool. To stress this wiki page not too much, here are some good tutorials:
Remember, your topic branch is yours, so no fear in rewriting history.