Skip to content

Commit d8c629c

Browse files
committed
reintroduce Committing section
relates #1
1 parent 2197e11 commit d8c629c

File tree

1 file changed

+44
-2
lines changed

1 file changed

+44
-2
lines changed

README.md

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,49 @@ Next, we should go back to the future. The quickest and easiest way is to checko
313313
![git reflog example](./img/git-reflog.png)
314314

315315
Find the commit name of the last commit you did (the third time that you recorded) and copy the short hash in yellow. Checkout back to that commit, and `git diff timeline-practise` there should be no difference.
316-
Checkout back to `timeline-practise` and push up to Github to make a pull request to master. Make sure you first check that it is up to date with master locally.
316+
Checkout back to `timeline-practise` and push up to Github to make a pull request to master. Make sure you first check that
317+
it is up to date with master locally.
318+
319+
320+
<a name="commits" id="commits"></a>
321+
## Committing
322+
323+
324+
<a name="when-commit" id="when-commit"></a>
325+
### When should you commit?
326+
327+
You should aim each commit to be a "safe" version of the project. This means that if you checkout to any commit in your timeline, that should reflect where the project was at that point, and be functional.
328+
329+
Given that, when you commit is very important. I have heard two very useful guidelines.
330+
331+
The first, is that as you complete the task assigned to you, you make several commits at different times during that task. In the end you merge all those commits together to make one very informative commit of that task. I will talk about ways to merge commits together in a later section.
332+
333+
The second method is you work through your task and complete it before adding or committing at all. Then you check the status of the repo and see all the files you have changed. The next step is selectively adding and committing
334+
335+
Through my research I have come across many different methodologies, and ultimately you should try to do what seems the most natural to you. I use both of these methodologies depending on the extent of the task before me. The best thing is to always keep in mind that you and your colleagues will inevitably need to go back to your commits and it will help everyone if commits are aptly named.
336+
337+
Likewise, even in pull requests, you must aim to make your commits a clear and concise summary of what tasks where completed on that branch. That way the person reviewing your pull request understands what they will be reviewing before looking at the code itself.
338+
339+
340+
<a name="commit-message" id="commit-message"></a>
341+
### Commit messages
342+
343+
Just like choosing when to commit, and what to commit, it is also important to think about your naming. It is always good to be as descriptive as possible with your commit messages.
344+
345+
Also consider:
346+
* Present tense for your commit messages
347+
* If related to an issue on github, should contain issue number
348+
* The first line should be 50 characters or less. Your message should be brief and to the point.
349+
* Focus on why you did something, not how you did it
350+
* Avoid `ands`. If you find yourself wanting to write `and`, you should probably break up that commit into multiple ones.
351+
352+
Remember that the purpose of this commit is to be a message for future you, or your colleagues who may not have known what you are working on. Try to think about your message with this in mind.
353+
354+
Many development teams take it one step further and turn their commit messages into change logs. These change logs may be used for user consumption making it all the more important to have clear messages of what was done for that commit.
355+
356+
I tend to favour one line commits for simplicity, but many schools of thought out there prefer multiline commit messages. For examples of "best practice" formats for this see:
357+
* [Commit message guidelines Angular](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format)
358+
* [Informative guidelines, and a cute cat filled slideshow](http://www.slideshare.net/TarinGamberini/commit-messages-goodpractices)
317359

318360

319361
<a id="merging-commits" name="merging-commits"></a>
@@ -334,7 +376,7 @@ git status
334376
git log
335377
```
336378

337-
Your working directory shouldn't change, but all the files that you changed should be in green. Your log should have the newest commit as the hash you copied. Even though all your work is still the same as before the reset, the commits are different. Then you can commit again and this is an easy way to replace 2 or more commits with one commit.
379+
Your working directory shouldn't changes, but all the files that you changed should be in green. Your log should have the newest commit as the hash you copied. Even though all your work is still the same as before the reset, the commits are different. Then you can commit again and this is an easy way to replace 2 or more commits with one commit.
338380

339381

340382
For more information and techiques see:

0 commit comments

Comments
 (0)