Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Review Ticket for 'Getting Started with GitHub Desktop' #14
The Programming Historian has received the following tutorial on 'An introduction to version control using GitHub Desktop' by @davanstrien. This lesson is now under review and can be read at:
I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.
Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.
I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to @ianmilligan1 if you feel there's a need for an ombudsperson to step in.
Hi @wcaleb and and @davanstrien, I've read through this document and am ready to make some comments. I think it is a clear guide. It is good because it introduces the user to the basics of git & github, while showing them on a very practical level how to being to make changes and commit them to a repo. In addition, I think it might be good to provide some explicit guidance to the user on the importance of maintaining a high quality commit history in their repository. My suggestions will relate to this theme.
Because git is so flexible it is very easy to create an exceedingly sloppy repository, but this is not advisable as the commit history tree is the guide to what you have done and the commit a message to your future self about what you did. In the case of a history document, it's a history of a history, and that's just cool!
In any case, while maintaining a high quality repo can be an advanced topic -- relating to how you branch, merge, and rebase when working -- here I think you can introduce the theme by talking about how to write high quality commits. So here are a couple of concrete topics that I think you might fruitfully instruct the user on in some fashion:
"Proper" commit style: You can write a commit message in any format, but this is not necessarily advisable. Programmers do it all the time, and it can look quite messy. Moreover, github and other git GUIs informally support certain commit message conventions, such that when you follow them you git messages will look better in those tools. For guidance, here's an authoritative post by Tim Pope on commit styles that was picked up by Github in 2011 as a basis for their "shiny new commit styles".
In addition, to the GUI benefits and the advisability of following conventions a bit, I think talking about commit messages is good because it's a chance for you to point out that commit messages can be more than just one-liners (although that's totally appropriate in many cases). The commit message can also provide some context about why a change was made, and this can be very very valuable. To return to the history of a history idea, this may also be of special value for the author using git as it provides a chance for a record of thoughts about alterations that are often lost, and a chance for self-reflection about edits. Tim Pope's article gives an example of an extended commit message and here's an example of mine:
"Atomic" commits: It is advisable when using git to ensure that all commits are "atomic", meaning that the changes in each commit leave the system in an altered, but still functional, state. The value of this is that each commit can be viewed as a complete set of changes, matching the description in the git commit message. Each commit then is a complete thought about how to change the system in a robust way. Later, when you or someone else has occasion to return to that commit, they can study it as a whole idea, instead of having to look at multiple commits in order to understand what the author did.
When maintaining software with git, this principle is important in other ways. It means, for example, that you can "rewind" you git history and inspect the functioning of the application at each state in the past without having to worry too much that the system won't function at any particular moment in its history. This is particularly useful, for example, when using a command like
So these are the main suggestions that I have. You might be interested in adding this git visualization tool to your list of additional resources, as it's particularly helpful for learning what is going on when you issue git commands.
Please let me know if you would like to discuss any of this further. Nice work!
Thanks, Ethan! Daniel, let's wait until the other reader's report appears to discuss or begin any potential revisions.
Sent from my iPhone
Thanks for this clear, helpful tutorial. As a novice GitHub user, I especially appreciate how clearly you explain the advantages of versioning and what "commit" entails--well done! The lesson is well-organized and approachable.
Let me offer some suggestions, most of which are pretty specific.
Questions and suggestions:
On the whole, this is a readable, straightforward and helpful tutorial. Thanks!
I plan to use parts of this tutorial in an Intro to GitHub workshop I'm doing on Monday. I'll let you know how it goes.
@ezmiller @lms4w many thanks for your comments. I have only had a chance to have a quick look but the comments look very helpful. I will be without much internet access this week but will make a start on implementing your suggestions at the weekend - I will get in touch if I have any questions or clarifications. Many thanks again for taking the time to look at this and provide these suggestions.
Happy to review the lesson--it's already been helpful to me.
I used the tutorial in a workshop I led today. On the whole, the workshop went well, but I did want to note a couple of issues:
Also I wonder if you might want to suggest that people try out Atom as their text editor, since it has integrated support for Markdown and other GitHub friendly features.
Thanks again for the lesson!
@lms4w great comments. @davanstrien you are welcome! I enjoyed reading through your tutorial. In my experience, git is a tool that can become incredibly complex and confusing. On the other hand, perhaps one of its strengths is that it is also a tool that you can start to use effectively without understanding every complex manipulation that is possible. So I appreciated that you kept the tutorial focused on what a beginner might want to do as a way to get started.
I was a little optimistic with my promised time frame for implementing changes.
I have not tried to address most of the comments in the review. @ezmiller I have attempted to expand the section discussing commit messages. I think this is a really useful consideration and something which I could definitely adopt more proactively.
@lms4w I have attempted to adopt most of your suggestions minus a couple:
I have hopefully addressed all of the other concerns. @wcaleb I have pushed these changes, what is the next step? Are there other things you think I still need to address/that need further work?
Many thanks to all of you for your contributions.
Thanks to all of you, and sorry @davanstrien that I've just been able to look over the changes you made.
It appears that when you merged some conflicts, there were several blocks of text that were left repeated in the lesson. I've gone through and done my best to fix these, and I've also made some other copyedits for clarity and style, so you may want to go through the commit history to see what I've done and make sure you approve.
I think this is almost ready for publication, but here's a list of a few things from the reviewers' suggestions that I think you could still address. If you want, you can check them off as you address them to keep track of what still needs to be done.
In addition to these issues, I have a couple suggestions of my own.
Let me know what you think. Hopefully these changes aren't too onerous and we can get this live soon! Appreciate all the work that all three of you have put into this!
I have hopefully added all of these suggestions and pushed them upstream without any issues. Please do let me know if anything looks out of place or unclear still. I am happy to keep working on this if needed. Thanks again for all the help and useful suggestions with this.