Tweaks and edits

Author: ben

book/06-github/sections/2-contributing.asc

@@ -40,7 +40,7 @@ Here's how it generally works:
 2. Make some commits to improve the project.
 3. Push this branch to your GitHub project.
 4. Open a Pull Request on GitHub.
-5. Discuss and optionally continue committing.
+5. Discuss, and optionally continue committing.
 6. The project owner merges or closes the Pull Request.
 
 This is basically the Integration Manager workflow covered in <<_integration_manager>>, but instead of using email to communicate and review changes, teams use GitHub's web based tools.
@@ -125,7 +125,7 @@ When you hit the 'Create pull request' button on this screen, the owner of the p
 
 [NOTE]
 ====
-Though Pull Requests are used commonly for public projects like this when the contributor has a complete change ready to be made, it's also often used in internal projects at the beginning of the development cycle.  Since you can keep pushing to the topic branch even *after* the Pull Request is opened, it's often opened early and used as a way to iterate on work as a team within a context, rather than opened at the very end of the process.
+Though Pull Requests are used commonly for public projects like this when the contributor has a complete change ready to be made, it's also often used in internal projects _at the beginning_ of the development cycle.  Since you can keep pushing to the topic branch even *after* the Pull Request is opened, it's often opened early and used as a way to iterate on work as a team within a context, rather than opened at the very end of the process.
 ====
 
 ===== Iterating on a Pull Request
@@ -137,7 +137,7 @@ Where this conversation may take place over email in the workflows presented in
 .Comment on a specific line of code in a Pull Request
 image::images/blink-04-pr-comment.png[PR line comment]
 
-Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. We'll go over customizing this later, but if you have email notifications turned on, Tony would get an email like this:
+Once the maintainer makes this comment, the person who opened the Pull Request (and indeed, anyone else watching the repository) will get a notification. We'll go over customizing this later, but if he had email notifications turned on, Tony would get an email like this:
 
 [[_email_notification]]
 .Comments sent as email notifications
@@ -221,7 +221,8 @@ Automatic merge failed; fix conflicts and then commit the result.
 $ vim blink.ino <4>
 $ git add blink.ino
 $ git commit
-[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' into slower-blink
+[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
+    into slower-blink
 
 $ git push origin slow-blink <5>
 Counting objects: 6, done.
@@ -253,9 +254,9 @@ If you absolutely wish to rebase the branch to clean it up, you can certainly do
 
 Your next question may be ``How to I reference the old Pull Request?''. It turns out there are many, many ways to reference other things almost anywhere you can write in GitHub.
 
-Let's start with how to cross-reference another Pull Request or an Issue. All Pull Requests and Issues are assigned numbers and they are unique within the project. For example, you can't have Pull Request #3 _and_ Issue #3. If you want to reference any Pull Request or Issue from any other one, you can simply put `#<num>` in any comment or description. You can also preface it with a `username` if you're referring to an Issue or Pull Request in a fork of the repository you're in, or `repo/username` to reference something in another repository.
+Let's start with how to cross-reference another Pull Request or an Issue. All Pull Requests and Issues are assigned numbers and they are unique within the project. For example, you can't have Pull Request #3 _and_ Issue #3. If you want to reference any Pull Request or Issue from any other one, you can simply put `#<num>` in any comment or description. You can also be more specific if the Issue or Pull request lives somewhere else; write `username#<num>` if you're referring to an Issue or Pull Request in a fork of the repository you're in, or `username/repo#<num>` to reference something in another repository.
 
-Let's look at an example. Say we rebased the branch in the previous example and want to reference the old pull request from the new one. We also want to reference an issue in the fork of the repository and an issue in a completely different project. We can fill out the description just like <<_pr_references>>.
+Let's look at an example. Say we rebased the branch in the previous example, created a new pull request for it, and now we want to reference the old pull request from the new one. We also want to reference an issue in the fork of the repository and an issue in a completely different project. We can fill out the description just like <<_pr_references>>.
 
 [[_pr_references]]
 .Cross references in a Pull Request.
@@ -344,7 +345,7 @@ image::images/markdown-04-fenced-code.png[Rendered fenced code]
 
 ====== Quoting
 
-If you're responding to a small part of a long comment, you can selectively quote out of the other comment by preceding the lines with the `<` character. In fact, this is so common and so useful that there is a keyboard shortcut for it. If you highlight text in a comment that you want to directly reply to and hit the `r` key, it will quote that text in the comment box for you.
+If you're responding to a small part of a long comment, you can selectively quote out of the other comment by preceding the lines with the `>` character. In fact, this is so common and so useful that there is a keyboard shortcut for it. If you highlight text in a comment that you want to directly reply to and hit the `r` key, it will quote that text in the comment box for you.
 
 The quotes look something like this:
 

book/06-github/sections/3-maintaining.asc

@@ -218,7 +218,7 @@ image::images/maint-05-mentions.png[Mentions]
 
 You can also mention a user who is not in that dropdown, but often the autocompleter can make it faster.
 
-Once mentioned, that user will be notified. This means that this can be a really effective way of pulling people into conversations rather than making them poll. Very often in  Pull Requests on GitHub people will pull in other people on their teams or in their company to review an Issue or Pull Request.
+Once you post a comment with a user mention, that user will be notified. This means that this can be a really effective way of pulling people into conversations rather than making them poll. Very often in  Pull Requests on GitHub people will pull in other people on their teams or in their company to review an Issue or Pull Request.
 
 If someone gets mentioned on a Pull Request or Issue, they will be ``subscribed'' to it and will continue getting notifications any time some activity occurs on it. You will also be subscribed to something if you opened it, if you're watching the repository or if you comment on something. If you no longer wish to receive notifications, there is an ``Unsubscribe'' button on the page you can click to stop receiving updates on it.
 
@@ -324,6 +324,6 @@ If you would like to transfer a project to another user or an organization in Gi
 .Transfer a project to anther GitHub user or Organization.
 image::images/maint-11-transfer.png[Transfer]
 
-This is helpful if you are abandoning a project and someone wants to take it over or if your project is getting bigger and want to move it into an organization.
+This is helpful if you are abandoning a project and someone wants to take it over, or if your project is getting bigger and want to move it into an organization.
 
 Not only does this move the repository along with all it's watchers and stars to another place, it also sets up a redirect from your URL to the new place. It will also redirect clones and fetches from Git, not just web requests.

book/06-github/sections/4-managing-organization.asc

@@ -45,7 +45,7 @@ To manage your Teams, you can click on the Teams sidebar on the right hand side
 .The Team page.
 image::images/orgs-02-teams.png[]
 
-When you invite someone to a team, they will get an email letting them know they've been invited and they have to accept the invitation.
+When you invite someone to a team, they will get an email letting them know they've been invited.
 
 Additionally, team `@mentions` (such as `@acmecorp/frontend`) work much the same as they do with individual users, except that *all* members of the team are then subscribed to the thread.
 This is useful if you want the attention from someone on a team, but you don't know exactly who to ask.

book/06-github/sections/5-scripting.asc

@@ -145,8 +145,6 @@ hs_err_pid*
 
 However, if you want to do an action on the website such as comment on an Issue or Pull Request or if you want to view or interact with private content, you'll need to authenticate.
 
-This also has the added advantage of increasing your rate limit. Without authenticating, you will be limited to 60 requests per hour. If you authenticate you can make up to 5,000 requests per hour.
-
 There are several ways to authenticate. You can use basic authentication with just your username and password, but generally it's a better idea to use a personal access token.
 You can generate this from the ``Applications'' tab of your settings page.
 
@@ -158,14 +156,16 @@ It will ask you which scopes you want for this token and a description. Make sur
 
 GitHub will only show you the token once, so be sure to copy it. You can now use this to authenticate in your script instead of using a username and password. This is nice because you can limit the scope of what you want to do and the token is revokable.
 
+This also has the added advantage of increasing your rate limit. Without authenticating, you will be limited to 60 requests per hour. If you authenticate you can make up to 5,000 requests per hour.
+
 So let's use it to make a comment on one of our issues. Let's say we want to leave a comment on a specific issue, Issue #6. To do so we have to do an HTTP POST request to `repos/<user>/<repo>/issues/<num>/comments` with the token we just generated as an Authorization header.
 
 [source,javascript]
 ----
 $ curl -H "Content-Type: application/json" \
        -H "Authorization: token TOKEN" \
        --data '{"body":"A new comment, :+1:"}' \
-https://api.github.com/repos/schacon/blink/issues/6/comments
+       https://api.github.com/repos/schacon/blink/issues/6/comments
 {
   "id": 58322100,
   "html_url": "https://github.com/schacon/blink/issues/6#issuecomment-58322100",
@@ -194,7 +194,7 @@ You can use the API to do just about anything you can do on the website -- creat
 
 One final example we'll look at since it's really useful if you're working with Pull Requests. Each commit can have one or more statuses associated with it and there is an API to add and query that status.
 
-Most of the Continuous Integration and testing services make use of this API to test commits that are pushed and then report back if that commit has passed all the tests. You could also use this to check if the commit message is properly formatted, if the submitter followed all your contribution guidelines, if the commit was validly signed -- any number of things.
+Most of the Continuous Integration and testing services make use of this API to react to pushes by testing the code that was pushed, and then report back if that commit has passed all the tests. You could also use this to check if the commit message is properly formatted, if the submitter followed all your contribution guidelines, if the commit was validly signed -- any number of things.
 
 Let's say you set up a webhook on your repository that hits a small web service that checks for a `Signed-off-by` string in the commit message.