GitHub Book

#GitHub Book Title: Introducing GitHub A Non-Technical Guide
By Peter Bell, Brent Beer
Publisher: O'Reilly Media
Final Release Date: November 2014
Pages: 142

##Who This Book Is For If you are working with developers on a software project, this book is for you,whether you are a:

• Business stakeholder who wants to have a sense of how your project is going
• Product or project manager who needs to ensure that software is delivered ontime and within budget
• Designer who needs to deliver anything from mockups to HTML/CSS for a project
• Copywriter who’s adding marketing copy or other content to a site or an app
• Lawyer who’s reviewing the legal implications of a project or writing the terms and conditions or privacy policy
• Team member who needs to review, comment on, and/or contribute to the project
• Developer who is new to using GitHub and wants to learn how to collaborate using GitHub in a team

If you need to view the progress of a piece of software while it’s being developed, if you would like to be able to comment on the progress, and if you’d like to have the option of contributing changes to the project, this book will show you how to effectively collaborate with a software development team by using GitHub.

##Who This Book Is Not For This book is designed to teach the core skills required to collaborate effectively using GitHub. If you are already familiar with forking, cloning, and using feature branches and pull requests for collaboration, you probably won’t learn that much. Equally, if you are looking for an in-depth introduction to the Git version control system, this is not the book that you are looking for.

This book covers just enough Git to do the job of introducing GitHub, but it’s not a comprehensive introduction to Git. For that you should read the excellent Version Control with Git by Jon Loeliger and Matthew McCullough (O’Reilly, 2012).

##Contents

1. Introduction................................................................ 1

   What Is Git? 1
   What Is GitHub? 1
   Why Use Git? 1
   Why Use GitHub? 2
   Key Concepts 3

2. Viewing.................................................................... 7

   Introducing the Project Page 7
   Viewing the README.md File 8
   Viewing the Commit History 9
   Viewing Pull Requests 11
   Viewing Issues 13
   Viewing the Pulse 15
   Viewing GitHub Graphs 16
   The Contributors Graph 17
   The Commits Graph 18
   The Code Frequency Graph 19
   The Punch Card Graph 20
   The Network Graph 21
   The Members List 22
   The Traffic Graph 23

3. Editing.................................................................... 25

   Contributing via a Fork 25
   Adding a File 26
   Creating a Pull Request 28
   Editing a File 36
   Renaming or Moving a File 39
   Working with Folders 41
   Creating a Folder 41
   Renaming a Folder 41
   The Limits of Editing on GitHub 42

4. Collaboration.............................................................. 43

   Committing to a Branch 43
   Creating a Pull Request from a Branch 46
   Collaborating on Pull Requests 48
   Involving People with Pull Requests 49
   Reviewing Pull Requests 49
   Commenting on Pull Requests 49
   Adding Color to Comments 50
   Contributing to Pull Requests 51
   Testing a Pull Request 53
   Merging a Pull Request 54
   Who Should Merge a Pull Request? 55
   Pull Request Notifications 55
   Best Practices for Pull Requests 56
   Issues 56
   Creating a New Issue 57
   Managing Milestones for Issues 58
   Managing Labels for Issues 60
   Commenting on Issues 61
   Referencing Issues in a Commit 61
   Best Practices for Issues 62
   Wikis 62
   Getting Started with a Wiki 62
   Adding and Linking to a Page on Your Wiki 65
   GitHub Pages 66
   Creating a Website for Your Project 66
   Creating a Website for Yourself or Your Organization 69

5. Creating and Conguring.................................................... 71

   Creating a Repository 71
   Adding Collaborators 76
   Configuring a Repository 77
   Integrating with Other Systems 79
   Personal Versus Organizational 85
   Creating an Organization 86
   Managing Teams 87

6. Downloading.............................................................. 93

   Why Clone a Repository? 93
   GitHub for Mac 94
   Making a Commit Using GitHub for Mac 103
   Viewing Changes in GitHub for Mac 106
   GitHub for Windows 109
   Making a Commit Using GitHub for Windows 116
   Configuring Command-Line Tools in GitHub for Windows 118

7. Next Steps............................................................... 121

Index....................................................................... 123

#Partial Quotes

Below are some quotes taken from the book that considered as necessary to be mentioned here as they will be a part of the discussed cases on this project documentation.

##Chapter 1. Introduction In this chapter we’ll start by introducing Git and GitHub. What are they, what is the difference between them, and why would you want to use them? We’ll then introduce some other common terms that you’ll often hear mentioned when people are discussing GitHub. That way you’ll be able to understand and participate in discussions about your projects more easily. ###Why Use Git? Even if you’re working on your own, if you are editing text files, there are a number of benefits to using Git. Those benefits include the following:

• The ability to undo changes
• A complete history of all the changes
• Documentation of why changes were made
• The confidence to change anything
• Multiple streams of history

Working on a team, you get an even wider range of benefits when using Git to keep track of your changes. Some of the key benefits of Git when working with a team are:

• The ability to resolve conflicts
• Independent streams of history

###Why Use GitHub? GitHub is much more than just a place to store your Git repositories. It provides a number of additional benefits, including the ability to do the following:

• Document requirements
• Collaborate on independent streams of history
• Review work in progress
• See team progress

###Key Concepts There are a number of key concepts that you’ll need to understand to work effectively with Git and GitHub. Here is a list of some of the most common terms with a short description of each and an example of how they might be used in conversation:

• Commit
• Commit message
• Branch
• Master branch (master)
• Feature (or topic) branch
• Release branch
• Merge
• Tag
• Check out
• Pull request
• Issue
• Wiki
• Clone
• Fork

##Chapter 2. Viewing In this chapter we’ll look at how you can view the state of a project to see what’s going on. We’ll use the popular Bootstrap open source project as an example. Bootstrap is a project that allows developers to quickly develop attractive web applications. Go to the project page on GitHub. ###Viewing Pull Requests Pull requests give you a sense of the current work in progress. Looking at the pull requests is a great way to get a sense of what people are working on now and the current state of play of each of those changes whether bug fixes or proposed features. ###Viewing Issues While pull requests give you a sense of the current bug fixes and features being worked on, issues can give you a wider sense of the outstanding work that still needs to be done on a project. Pull requests are often linked to an issue, but there will usually also be issues that nobody has started working on yet, so they don’t yet have a pull request. ###Viewing the Pulse The pulse is a great way to get a sense for the recent activity on a project. You can customize the pulse to be for the last day, three days, week, or month. The pulse starts with an overview of the number of pull requests that have been merged (completed) and proposed (added). It also shows how many issues were closed or opened. It’s important to understand that when the pulse refers to the number of active pull requests and issues, this is not the outstanding number of each but rather the number of requests and issues that have been started and finished in the time period you selected. ###Viewing GitHub Graphs While the pulse gives you a summary of recent activity, the graph pages allow you to get a sense of the work that has been done on a project over a longer period of time. ###The Punch Card Graph The punch card graph displays a circle for every hour of every day in the week. The diameters of the circles are a function of the percentage of the commits for the project made during that hour on that day. The bigger the circle, the more of your project commits have been made at that time. Again, this a great way to get insight into the times when your team is most productive. ####The Traffic Graph The traffic graph shows you the number of views and unique visitors over time, lists the sites that people are linking from, and highlights the most popular content on your GitHub project site. It can be a great way to get a sense of the popularity for open source projects.

##Chapter 3. Editing In this chapter we’ll look at how you can contribute to a project. We’ll start by looking at how to contribute to a project that you don’t have permission to push to by creating a fork and a pull request. We’ll then look at how you can add, edit, rename, or delete a file directly on GitHub. We’ll also look at how to work with directories on GitHub, and finally we’ll discuss what to do when you want to make multiple changes as part of a single commit. ###Contributing via a Fork If you want to contribute directly to a project, you either need to own it or have been added to it as a collaborator. If you want to contribute to a project that you don’t own and are not a collaborator on, you’ll need to make a copy of it on GitHub under your user account. Once you’ve forked the repo, you can make any changes you want to your fork (copy). ###Creating a Pull Request Anyone can fork any public project, and the project owner wouldn’t want just anyone editing all of their files. However, sometimes it’s great to allow other people to propose changes to a project. This allows a large number of people to easily contribute to an open source project or a smaller team to work together on an internal project. That is what pull requests are for. ###Renaming or Moving a File Often you want to rename a file or move it from one folder to another. As far as Git and GitHub are oncerned, both are the same process: you’re changing the full name for the file, and optionally including the name of its folder. ###Working with Folders It is important to understand how Git thinks about folders—it doesn’t! Git is concerned only with files. As far as it is concerned, folders are simply a place to store those files. Because of that, there is no way to add a folder to a project unless it includes at least one file. Sometimes this is a problem. For example, in many software projects there needs to be a /build folder where automatically generated files will be saved when compiling the software. With some systems, if you don’t have such a folder, you’ll be unable to use the project. ####Creating a Folder A common pattern that has emerged is to create an empty file called .gitkeep in any folder that you need to create but that doesn’t really need to have any files. It seems a bit strange, but it works well and it is a well-understood convention, so if you ever need to create a folder, just create a .gitkeep file. ####Renaming a Folder There is no way you can just rename a folder on GitHub. You’d have to rename each of the files in the folder one at a time to move them to the new folder. ###The Limits of Editing on GitHub We have just run into one of the limitations of editing on GitHub. Originally GitHub was designed to allow developers to share their Git repositories with each other. Developers would make changes to their projects locally on their laptops, save those changes in Git, and then push the results to GitHub. Now that more and more non technical people are collaborating via GitHub, it’s possible to do much of your editing right on the site, but there are a number of things that you can’t do via the web-based interface. Currently, GitHub doesn’t allow you to rename folders or to make any other changes to more than one file in a single commit. It also doesn’t give you the power of Git to rewrite history, and it doesn’t allow you to resolve conflicts online, so if there is a pull request that conflicts with another change, someone is going to have to download (clone) a copy of the repo, fix the changes, and push them back up to GitHub. If you want to learn the basics of working with Git locally, check out the instructions in Chapter 6 for getting started with GitHub for Mac or Windows. For now, though, we’re going to look at how to collaborate effectively with your team using GitHub. ##Chapter 4. Collaboration In this chapter we’ll start by looking at how to collaborate directly on a single repository without using forks. We’ll then take some time to look more deeply into collaborating using pull requests, issues, and GitHub pages. While forks are a good way to accept contributions from people you don’t work with regularly, they are a bit too cumbersome for everyday use in a team that is working together closely. Because of this, you’re probably going to want to collaborate directly on a single repository. However, it’s still important to use branches and pull requests to keep your work separate.