New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Review Ticket for 'Getting Started with GitHub Desktop' #14

Closed
wcaleb opened this Issue Mar 17, 2016 · 15 comments

Comments

4 participants
@wcaleb
Contributor

wcaleb commented Mar 17, 2016

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:

http://programminghistorian.github.io/ph-submissions/lessons/getting-started-with-github-desktop

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.

Anti-Harassment Policy
_

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudspersons (Ian Milligan or Miriam Posner - http://programminghistorian.org/project-team). Thank you for helping us to create a safe space.

_

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented Mar 23, 2016

Two reviewers have been contacted and will post their reviews here within the next couple of weeks. Stay tuned, @davanstrien!

@ezmiller

This comment has been minimized.

ezmiller commented Mar 27, 2016

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 git bisect which can help you track down which commit was responsible for a given bug. But I think this same principle will be useful for those maintaining textual repositories as well. They are systems too in a way. In any case, combined with proper git message styles, ensuring that each commit is atomic will mean that an author can navigate back through their repo history and see in each commit a complete idea about a chance with some introspection about that change. This is what a healthy repo history should look 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!

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented Mar 27, 2016

Thanks, Ethan! Daniel, let's wait until the other reader's report appears to discuss or begin any potential revisions.

Sent from my iPhone

On Mar 27, 2016, at 6:55 AM, Ethan Miller notifications@github.com wrote:

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 git bisect which can help you track down which commit was responsible for a given bug. But I think this same principle will be useful for those maintaining textual repositories as well. They are systems too in a way. In any case, combined with proper git message styles, ensuring that each commit is atomic will mean that an author can navigate back through their repo history and see in each commit a complete idea about a chance with some introspection about that change. This is what a healthy repo history should look like!

So these are the main suggestions that I have. You might be interested in adding this git visulization 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!


You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

@ezmiller

This comment has been minimized.

ezmiller commented Apr 7, 2016

@wcaleb @davanstrien how's the conversation going here? Curious what you guys are thinking.

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented Apr 7, 2016

@ezmiller We're just waiting on the second review to come in before picking up the discussion. Thanks for your patience and for your very helpful feedback!

@lms4w

This comment has been minimized.

lms4w commented Apr 8, 2016

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:

  • You might want to mention that students and researchers are eligible to receive free GitHub repositories: https://education.github.com/pack and https://github.com/blog/1840-improving-github-for-science
  • Consider presenting a few examples of how GitHub used for academic writing projects so that readers have models to explore. When is GitHub a good tool to use, and when is it not? (As opposed to, say, versioning available through services like Box or wikis.)
  • Briefly explain what distinguishes Git as an approach to version control (e.g. Git's distributed approach).
  • I'd be interested in learning more about how GitHub can be used to "contribute and draw upon other projects." Would a section on pull and merge requests fit into this lesson, or do you envision a future lesson on this topic?
  • I suspect that one concern of novice GitHub users is making files public prematurely. How can one prevent this--by not syncing?
  • Is there any difference between how GitHub is used for writing projects and how GitHub is employed for coding?
  • How do we indicate which versions of files to version control in GitHub Desktop? I'm assuming it's through committing changes, but that can be made clear earlier.
  • I think you need to explain the term "master," so the user knows what it means to "Commit to master."
  • I appreciate the emphasis on the need to provide clear commit messages. As @ezmiller suggested, it would be helpful to see some principles for documenting commits. It might also be useful to provide a few models. Folks familiar with wikis may find the practice of summarizing changes when saving on a wiki a useful analogy.
  • Are there any suggestions for organizing and describing files in GitHub?
  • When you say "To quickly view your repository online you can use the repository menu," make specific that the user should select "View on GitHub."
  • The "Publishing a repository" screenshot may be confusing as it seems that you have a paid account and thus can keep code private. Perhaps use a screenshot from the free version or explain that you have the paid plan?
  • I think it might be helpful to briefly explain the key concepts such as "repository," "push," "pull," "fork," "branch," and "sync," as these terms tend to confuse newcomers. Alternatively, you could let readers know that these concepts will be discussed in future lessons or point them to a glossary.
  • How does GitHub reconcile conflicts between the local and web-based repositories?
  • What do I lose if I use GitHub Desktop instead of the command-line or web interface? What do I gain?
  • A brief explanation of Raw, Blame and History might be useful.
  • It might be helpful to explain the basic interface in both GitHub Desktop and the web version; I found helpful the schematic of the web interface available here http://blog.udacity.com/2015/06/a-beginners-git-github-tutorial.html You might explain that the comparison graph under the Sync button allows you to scroll through the history of commits.
  • How can you roll back to earlier versions of a document?
  • It might be helpful to point to other ways you can use GitHub, e.g. for collaboration.
  • Should you discuss README.md files?
  • I think the "Other Resources" section might be fleshed out a bit. Consider adding:

Mechanical errors

  • The entire lesson could use a round of proofreading.
  • What is Git and GitHub? --> What are Git and GitHub?
  • Firstly (in "What is Version Control and Why Use It?") implies that there will be a "second."
  • I'd suggest using "while" instead of "whilst," since it is less formal.
  • Make sure that the H in GitHub is consistently capitalized.
  • Use a dash rather than a hyphen (-).
  • integrates it’s --> integrates its
  • straight forward --> straightforward.
  • "using the push and pull commands use on the command line." Should that be "used"?
  • re-enforcing--> reinforcing
  • Pay attention to comma errors throughout. For example:
  • how to implement version control using ‘GitHub Desktop**,**’ a Graphical User Interface for GitHub.
  • Although GitHub’s focus is primarily on source code**,** other projects,

Overall

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.

@davanstrien

This comment has been minimized.

Contributor

davanstrien commented Apr 11, 2016

@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.

@lms4w

This comment has been minimized.

lms4w commented Apr 11, 2016

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:

  1. The top toolbar didn't display in the PC version of GitHub Desktop. I'm on a Mac myself, but as I understand it the PC version is somewhat different.

  2. A couple of people ran into issues where the first file they added to GitHub Desktop did not sync properly to GitHub. Maybe there was an issue with initializing GitHub? (At least one hadn't used GitHub before.)

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!

@ezmiller

This comment has been minimized.

ezmiller commented Apr 12, 2016

@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.

@davanstrien

This comment has been minimized.

Contributor

davanstrien commented May 20, 2016

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:

  • distributed version control - I am still undecided but think this might be best saved for a future lesson on collaboration when this point becomes more pertinent.
  • ditto with the section on collaborating. I think this would fit nicely in a separate lesson.
  • rolling back to an earlier version - I'm still a bit unsure about this. This is definetly somethign people are keen to be able to do but again I thought it might be better contained in a more 'advanced' lesson that also covered merges, conflicts, etc.

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.

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented May 24, 2016

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.

  • Mentioning collaboration, suggested by @lms4w. I agree with you that a full explanation of how to collaborate is better left for a different lesson, but perhaps in the section on "why version control text documents," you could expand the last bullet point into its own paragraph explaining, at a very general level, how this would work (i.e., that version control would allow you to compare two people's separate documents and merge them together into a third version).
  • Paraphrase Pope blockquote. I like the new suggestions about commit messages, per @ezmiller, but I think including the full blockquote from Tim Pope could be confusing to beginners, because it uses terms you haven't discussed (like "rebase") and also is geared more towards code. Could you paraphrase his suggestions into a shorter summary instead of quoting them verbatim?
  • Premium versus free private repositories. You've now added links suggesting that academics can get free private repos, but elsewhere in the lesson you say they will need a premium account. And as @lms4w points out, one of the screenshots refers to billing info. So some explanation of this is needed, probably near the screenshot.
  • How to "roll back." If you would rather not address how to do this, you could at least say something like "although not discussed in this lesson, Git will also allow you to checkout earlier versions of your file and even restore a particular snapshot."
  • Wiki analogy. I think @lms4w's suggestion of giving beginners an analogy between commit messages and Wikipedia or wiki change descriptions is a good one, and would help demystify this process.
  • Reconciling conflicts between remote and local. I think this is something that you probably should address, because it's a problem a beginner is likely to encounter. Suppose they make a change on the website and then, before syncing, make another, different change to their local file. What will happen when they "Sync?" Walking through an example of how GitHub Desktop would manage this conflict would be useful, and could also be another way of highlighting why version control this way is better than simple sync through Dropbox, which would just create two copies of the file.
  • Include Atom. When mentioning your text editors, you could easily link to Atom as per @lms4w suggestion.

In addition to these issues, I have a couple suggestions of my own.

  • Include screenshot of folder prior to first screenshot of GitHub Desktop. The Desktop interface doesn't make super clear that git-gui is nothing but a folder elsewhere on the Mac. Perhaps give a screenshot of a Finder window showing that all you've done is create a folder. This will make it easier for beginner to understand what you mean by "dragging the folder" to Desktop. Alternatively or in addition, you could add a screenshot showing the file picker that would pop up when you click the "plus" button.
  • "hello world a second line." In your local file examples, the second line always appears on a second line. But once you show the reader the web version, all the words appear on one line. This is because, as you've mentioned earlier, GitHub renders the file in Markdown, and in order for Markdown to recognize paragraphs, there has to be a space between. I think it would be too much for you to go back and change all screen shots and examples to insert that blank line. But you could use the potentially puzzling "hello world a second line" screenshot as an opportunity to briefly review Markdown and show the difference that it makes. You could also mention that had the file been named ".txt" instead of ".md," this would not have happened. (That extension should probably be explained anyway, because earlier you've referred to plain text files as ".txt.")

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!

@davanstrien

This comment has been minimized.

Contributor

davanstrien commented May 29, 2016

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.

wcaleb added a commit that referenced this issue Jun 16, 2016

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented Jun 16, 2016

@davanstrien The lesson looks great! Please look over the few changes I have made in 9f87a1a. If you approve of all of them, then I think this is ready to publish live!

@davanstrien

This comment has been minimized.

Contributor

davanstrien commented Jun 17, 2016

I have had a look at the proposed changes and they all look good to me. Very excited to see it go live! Many thanks again @wcaleb @lms4w and @ezmiller for all of your help and suggestions.

@wcaleb

This comment has been minimized.

Contributor

wcaleb commented Jun 17, 2016

Done! The lesson is live. Please tweet the lesson a few times and get the word out!

@wcaleb wcaleb closed this Jun 17, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment