Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
github_best_practices [2018/08/31 23:29] – [After Successful Test] Traumflug | github_best_practices [2019/10/05 14:00] (current) – [File Permissions] Clarify link. Traumflug | ||
---|---|---|---|
Line 11: | Line 11: | ||
* [[https:// | * [[https:// | ||
- | * [[https:// | + | * [[https:// |
+ | For refreshing the repository view in Gitk, menu -> //File// -> //Update// (F5) is often incomplete. Menu -> //File// -> //Reload// (Shift-F5) is the much better choice. | ||
+ | |||
+ | ===== Merging is Evil ===== | ||
+ | |||
+ | {{ : | ||
+ | Ouch? Well, let's refine the sentence: " | ||
+ | |||
+ | 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: | ||
+ | |||
+ | * Use [[https:// | ||
+ | * Use [[https:// | ||
+ | * Use [[https:// | ||
+ | |||
+ | 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. | ||
===== Avoid broken Code on the Main Branch ===== | ===== 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. | 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, | + | However, |
A "topic branch" | A "topic branch" | ||
Line 26: | Line 44: | ||
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. | 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: | + | As one can see, I simply use a topic branch |
{{ : | {{ : | ||
Line 40: | Line 58: | ||
==== After Successful Test ==== | ==== After Successful Test ==== | ||
- | After Travis CI tested | + | If Travis CI tests found no flaws, |
<code none> | <code none> | ||
git checkout 1.0.x | git checkout 1.0.x | ||
Line 55: | Line 73: | ||
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 [[https:// | 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 [[https:// | ||
- | Task done. Don't forget to switch back to the topic branch before picking up the next task: | + | Task done. Don't forget to switch back to the topic branch before picking up on the next task: |
<code none> | <code none> | ||
git checkout markus | 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 '' | ||
+ | <code none> | ||
+ | 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 '' | ||
+ | <code none> | ||
+ | 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 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: | ||
+ | |||
+ | * [[https:// | ||
+ | * [[https:// | ||
+ | * [[https:// | ||
+ | * [[https:// | ||
+ | |||
+ | Remember, your topic branch is __yours__, so no fear in rewriting history. | ||
+ | ===== Picking Pull Requests ===== | ||
+ | |||
+ | It's as simple as clicking the //Merge pull request// button on the Github web page, right? Wrong. | ||
+ | |||
+ | This button has flaws: | ||
+ | |||
+ | * No review possible. Well, one can stare at the commit, of course, but not edit or test it. | ||
+ | * Potential to write a nonlinear history. Drawbacks see [[#Merging is Evil]] above. | ||
+ | * Pointless work for those creating the pull request. A simple link to a commit in another repository works just as well. | ||
+ | |||
+ | One can easily ignore this button. Picking pull requests, or any commit on Github, is pretty trivial: | ||
+ | |||
+ | - Find the commit on Github. It's an URL like '' | ||
+ | - Append '' | ||
+ | - In your local repository clone, proceed like this: | ||
+ | <code none> | ||
+ | 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. | ||
+ | |||
+ | ===== Dealing with Github Issues ===== | ||
+ | |||
+ | Here are some hints on good practices when dealing with Github issues. | ||
+ | |||
+ | == Issue reports are of value == | ||
+ | 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. | ||
+ | |||
+ | == Steps to reproduce == | ||
+ | Good Github issues come with a list of steps to reproduce. Like: | ||
+ | |||
+ | - Have a fresh shop installation. | ||
+ | - Install this. | ||
+ | - Change this setting to that. | ||
+ | - Expected behavior: [...] | ||
+ | - Actual behavior: [...] | ||
+ | - Screenshot, showing the flaw. | ||
+ | |||
+ | 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, | ||
+ | |||
+ | == Talk == | ||
+ | If an issue can get fixed immediately, | ||
+ | |||
+ | == Issue reporters close issues == | ||
+ | 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' | ||
+ | |||
+ | == Issues get reported for a reason == | ||
+ | One can often see issues getting closed within minutes with //' | ||
+ | |||
+ | It's a good idea to keep in mind that people usually don't write issue reports because they' | ||
+ | |||
+ | |||
+ | ===== This and That ===== | ||
+ | |||
+ | A couple of smaller tasks, in loose order. | ||
+ | |||
+ | ==== Recovery From a Failed Stash Pop ==== | ||
+ | |||
+ | In some situations a '' | ||
+ | |||
+ | Knowing the secret, recovery is simple: | ||
+ | <code none> | ||
+ | git stash drop | ||
+ | git reset . | ||
+ | </ | ||
+ | |||
+ | ==== File Permissions ==== | ||
+ | |||
+ | 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>/ | ||
+ | |||
+ | Then follow instructions at [[Developer Installation# | ||
+ | |||
+ | That done, move //.git// back: | ||
+ | |||
+ | $ mv /tmp/.git <git repository>/ | ||
===== References ===== | ===== References ===== |
github_best_practices.1535750968.txt.gz · Last modified: 2018/08/31 23:29 by Traumflug