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.
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.
gitk --all&in the repository to browse.
For refreshing the repository view in Gitk, menu -> File -> Update (F5) is often incomplete. Menu -> File -> Reload (Shift-F5) is the much better choice.
Which code changes led to release 184.108.40.206-RC3 and which branch should be taken when searching backwards in history for finding a regression?
Ouch? Well, let's refine the sentence: “Non-fast-forward merges are evil”.
Believe it or not, I use Git since it's early days, use it many times a day, and I never merged anything. It felt wrong from the beginning and today, quite some experience joined this feeling.
The simple reason can be seen on the right: extensive use of merges creates an messy history and having nothing but a mess makes having a history almost pointless.
Maintaining a linear history isn't too hard:
A number of expert tasks, e.g. interactive rebasing or filtering, works on linear histories, only. Git simply flattens the history in such cases, which not only removes most commit messages, it can also cause a lot of conflicts.
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, flawed 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.
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 named markus for everyday work:
Then this branch gets pushed, which triggers a Travis CI run:
git push thirtybees markus
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.
If Travis CI tests found no flaws, the main branch gets forwarded to the topic branch:
git checkout 1.0.x git rebase --autostash markus
Then push the new main branch:
git push thirtybees 1.0.x
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 on the next task:
git checkout markus
Test failures are no big deal as long as they happen on a topic branch. Now two things should happen:
The latter is essential, else the broken commit will stay broken, with all the drawbacks described above.
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 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:
Local and remote Git hashes are no longer the same. To nevertheless push this branch, one needs the additional
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, or continue in section After Successful Test.
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.
It's as simple as clicking the Merge pull request button on the Github web page, right? Wrong.
This button has flaws:
One can easily ignore this button. Picking pull requests, or any commit on Github, is pretty trivial:
.patchto this URL:
curl -L <URL> | git am -3
That's it! After this simple oneliner, one has this commit on top of the local branch, including author info and commit timestamp. Now one can review this commit, run the local shop installation with it, add remarks in the commit message, push it on a topic branch for a Travis CI run, and so on. Easy, and much more reliable.
Here are some hints on good practices when dealing with Github issues.
As unfortunate as it is, code has inevitably flaws. Now think of a given set of code, and the same set of code, together with a description of its flaws. The latter is undoubtly of more value.
The only situation even better than code together with a description of its flaws is code with these flaws actually fixed.
Good Github issues come with a list of steps to reproduce. Like:
First thing when attempting to fix a flaw is to reproduce the issue. If there is no list of steps to reproduce the bug, add it in a comment. This way everybody participating knows what's going on. If the issue appears to be not reproducible, for the lack of a description or the lack of a bug or because it was fixed already, ask the issue reporter.
If an issue can get fixed immediately, great! If not, it's a good idea to add comments about partial successes. Or things which were tried, but didn't work out.
Many projects have the habit to close issue reports quickly. Sometimes by writing some magic words into the commit message.
Closing a Github issue doesn't make the issue in code going away. As the issue reporter knows best whether something was actually fixed, it's a good idea to ask him and let him decide whether the issue is actually solved. Reports just waiting for an answer of the reporter don't hurt.
One can often see issues getting closed within minutes with 'works as expected', especially in popular, matured projects.
It's a good idea to keep in mind that people usually don't write issue reports because they're bored. They do have an issue. Maybe the user interface isn't intuitive. Maybe software behavior can get improved. Getting such seemingly wrong reports is often a sign there's some room for improvement. This should be leveraged. thirty bees should be easy and intuitive to use, even for newbies.
A couple of smaller tasks, in loose order.
In some situations a
git stash pop or a command using the
--autostash parameter doesn't restore the repository to its previous state. Instead it mumbles something about “need merge” or something.
Knowing the secret, recovery is simple:
git stash drop git reset .
A typical problem of developer installations is trouble with file permissions. While the Git repository is owned by the developer, the web server runs as another user. Result: developer can't edit files created by the web server and vice versa.
Solution is to use extended file permissions. First, move .git aside:
$ mv <git repository>/.git /tmp
Then follow instructions at Developer Installation.
That done, move .git back:
$ mv /tmp/.git <git repository>/