Sectionize chapter 6

Author: ben

book/06-github/1-github.asc

@@ -0,0 +1,30 @@
+=== The API
+
+(((GitHub, API)))
+If the web UI isn't enough for you, or you're writing a program that works with GitHub projects, you'll be happy to know that GitHub has an API.
+It works over HTTPS, so it's fairly easy to try out:
+
+[source,shell]
+----
+$ curl https://api.github.com/user/schacon
+{
+  "login": "schacon",
+  "id": 70,
+  "avatar_url": "https://avatars.githubusercontent.com/u/70?",
+# …
+  "following": 19,
+  "created_at": "2008-01-27T17:19:28Z",
+  "updated_at": "2014-06-10T02:37:23Z"
+}
+----
+
+Most everything you can do from the GitHub web interface or from Git itself can be done through this API, as well as some things that can't.
+Remember how `gh` can convert an issue into a pull request?
+That's accomplished using the a `POST` to the `/repos/<owner>/<repo>/pulls` endpoint.
+
+Several open-source libraries exist that make this API available in an idiomatic way.
+At the time of this writing, the supported languages include Go, Objective-C, Ruby, and .NET.
+Check out http://github.com/octokit[] for more information on these, as they handle much of the HTTP for you.
+
+There's much more to the API than is possible to cover in this book.
+Take a look at https://developer.github.com[] for the complete documentation, as well as guides for common tasks.

book/06-github/sections/api.asc

@@ -0,0 +1,111 @@
+=== Discussions
+
+(((GitHub, discussions)))
+Pull Requests and Issues both fall under the heading of ``discussions.''
+These discussions have some interesting features that make them especially useful when working on software.
+Let's take a look at when you should use each one, and how best to use them.
+
+[[_github_pull_requests]]
+==== Pull Requests and Issues
+
+Pull Requests and Issues seem like completely different things, but in reality they're the same.
+A Pull Request is actually just an Issue with a Git branch attached.
+Apart from that, they are identical; both have a title, description, and comments; both can belong to a Milestone; both trigger notifications; and so on.
+They're used for very different things, however.
+
+An Issue is used to report a problem, or post a reminder for work to be done later, or just to ask a question.
+Pull Requests, on the other hand, are used to propose a change.
+These lines aren't cut into stone, however; some of the most effective bug reports are Pull Requests that include a test that isolates the problem.
+
+==== Markdown
+
+(((Markdown)))
+One of the features that all discussions share is Markdown.
+Markdown is a way of decorating plain text that adds emphasis and structure.
+It's designed to be readable without any extra processing, but also to be translated into richly formatted HTML.
+
+An example might help.
+Markdown looks like this:
+
+[source,markdown]
+----
+*Italics* and **bold text** are possible. So are [links][github].
+
+[github]: http://github.com/
+----
+
+That block of text renders in a GitHub description or comment like this:
+
+////////////////////////////////////////////////////////////////
+Yeah, I'm cheating. Sue me.
+////////////////////////////////////////////////////////////////
+====
+_Italics_ and *bold text* are possible. So are http://github.com/[links].
+====
+
+In addition to the basics, GitHub includes Markdown features that are tailored to the needs of developers.
+A good example of this is fenced code blocks, which look like this:
+
+[source,markdown]
+----
+```ruby
+puts "Hello, Markdown!"
+```
+----
+
+The text between the triple-backquote markers (+```+) will be treated as code, and ignored by Markdown.
+GitHub will try to detect what language the code snippet is in and provide syntax highlighting; you can give it a hint as to the language with a name just after the opening block (+```ruby+ above).
+
+(((emoji)))
+Another sometimes-useful, sometimes silly feature is Emoji integration.
+If a picture is worth a thousand words, an Emoji can sometimes be worth five or ten.
+GitHub translates the text +:sheep::dash:+ into a pictorial representation that looks like this:
+
+.+:sheep::dash:+ rendered.
+image::images/emoji.png[+:sheep::dash:+ rendered.]
+
+GitHub-flavored Markdown can do even more than this, including tables, checklists, and autolinks.
+Take a look at https://help.github.com/articles/github-flavored-markdown[] for a complete description.
+
+==== Notifications
+
+(((GitHub, notifications)))
+In order to contribute to or manage a project, you need to know what's going on.
+GitHub keeps you informed through a mechanism called notifications.
+You'll receive notifications for event streams in several kinds of situations.
+If you're ``watching'' a repository, you'll get notified of new issues and pull requests; comments on issues, pull requests, and commits; and newly published releases.
+If you're not watching a repository, you'll only be subscribed to a discussion if you're the target of an `@mention`, if an issue is assigned to you, if you've commented on a thread, or if a comment is added to something you made (a commit, or discussion).
+
+An `@mention` is a handy way to get someone's attention.
+If you include `@john` in a comment, the user named `john` is notified of your comment, and automatically subscribed to the discussion thread that comment is on.
+This is a great way of managing your notification volume; large teams can generate a lot of them, so you can control when you participate.
+
+==== Email
+
+Notifications arrive through two channels: the notifications view at https://github.com/notifications[], and via email.
+This is controlled by the settings at https://github.com/settings/notifications[].
+
+.Notification settings.
+image::images/notifications.png[Notification settings.]
+
+The email notifications have a couple of unique features.
+Firstly, you can simply reply to an email, and your comment will show up in the discussion thread, almost as though you went to the website and typed it in.
+The main difference is that email replies won't be Markdown-formatted.
+
+The emails are also designed to dovetail with Gmail's ``mute'' feature:
+
+* If you're subscribed to a discussion that you're not actively participating in, and that you're not interested in, you can mute the thread in Gmail.
+* If you are then summoned with an `@mention` in the thread, the email notification will have you in the `cc` field, which bypasses the mute filter and shows you the email thread again.
+
+==== Autolinked Discussions
+
+Just one more thing before we leave discussions behind.
+GitHub's Markdown parser can also link to other discussions.
+Writing text like `this is just like #49` will change ``#49'' into a link to the issue or pull request whose number is 49.
+A back-link will also be inserted into the discussion thread on the target discussion (though this doesn't trigger a notification).
+
+This is a great way of networking discussions together, but it has another benefit.
+If you write something like `fixes #7` or `closes #739` in a pull request description or commit message, the target issue will be closed whenever the PR is merged, or the commit becomes reachable from the `master` branch.
+This is really great for fixing bugs or managing user stories.
+
+Next, let's talk about how to match up repositories and people.

book/06-github/sections/discussions.asc

@@ -0,0 +1,130 @@
+[[_github_flow]]
+=== The GitHub Flow
+
+(((GitHub, Flow)))
+GitHub is designed around a particular collaboration workflow, centered on Pull Requests.
+This flow works whether you're collaborating with a tightly-knit team in a single shared repository, or a globally-distributed company or network of strangers contributing to an project through dozens of forks.
+It is centered on the <<_topic_branch>> workflow covered  in <<_git_branching>>.
+
+Here's how it generally works:
+
+1. Create a topic branch from `master`.
+2. Make some commits to improve the project.
+3. Open a Pull Request on GitHub.
+4. Discuss and continue committing.
+5. 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.
+
+Let's walk through an example of proposing a change to an open source project hosted on GitHub using this flow.
+
+==== Example Contribution Cycle
+
+Tony is looking for code to run on his Arduino programmable microcontroller and has found a great program file on GitHub at https://github.com/schacon/blink[].
+
+.The project we want to contribute to.
+image::images/blink-start.png[The project we want to contribute to.]
+
+The only problem is that the blinking rate is too fast, we think it's much nicer to wait 3 seconds instead of 1 in between each state change. So let's improve the program and submit it back to the project as a proposed change.
+
+First, we click the 'Fork' button as mentioned earlier to get our own copy of the project. Our user name here is ``tonychacon'' so our copy of this project is at `https://github.com/tonychacon/blink` and that's where we can edit it. We will clone it locally, create a topic branch, make the code change and finally push that change back up to GitHub.
+
+[source,shell]
+----
+$ git clone https://github.com/tonychacon/blink <1>
+Cloning into 'blink'...
+
+$ cd blink
+$ git checkout -b slower-blink <2>
+Switched to a new branch 'slower-blink'
+
+$ sed -i '' 's/1000/3000/' blink.ino <3>
+
+$ git diff --word-diff <4>
+diff --git a/blink.ino b/blink.ino
+index 15b9911..a6cc5a5 100644
+--- a/blink.ino
++++ b/blink.ino
+@@ -18,7 +18,7 @@ void setup() {
+// the loop routine runs over and over again forever:
+void loop() {
+  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
+  [-delay(1000);-]{+delay(3000);+}               // wait for a second
+  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
+  [-delay(1000);-]{+delay(3000);+}               // wait for a second
+}
+
+$ git commit -a -m 'three seconds is better' <5>
+[master 5ca509d] three seconds is better
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+
+$ git push <6>
+Username for 'https://github.com': tonychacon
+Password for 'https://[email protected]':
+Counting objects: 5, done.
+Delta compression using up to 8 threads.
+Compressing objects: 100% (3/3), done.
+Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
+Total 3 (delta 1), reused 0 (delta 0)
+To https://github.com/tonychacon/blink
+ * [new branch]      slower-blink -> slower-blink
+----
+
+<1> Clone our fork of the project locally
+<2> Create a descriptive topic branch
+<3> Make our change to the code
+<4> Check that the change is good
+<5> Commit our change to the topic branch
+<6> Push our new topic branch back up to our GitHub fork
+
+Now if we go back to our fork on GitHub, we can see that they noticed that we pushed a new topic branch up and present us with a big green button to check out our changes and open a Pull Request to the original project.
+
+.Pull Request button
+image::images/blink-pr.png[Pull Request button]
+
+(((GitHub, pull requests)))
+If we click that green button, we'll see a screen that allows us to create a title and description for the change we would like to request so the project owner has a good reason to consider it. It is generally a good idea to spend some effort making this description as useful as possible so the author knows why this is being suggested and why it would be a valuable change for them to accept.
+
+We also see a list of the commits in our topic branch that are ``ahead'' of the `master` branch (in this case, just the one) and a unified diff of all the changes that will be made should this branch get merged by the project owner.
+
+.Pull Request creation page
+image::images/blink-pull-request-open.png[Pull Request creation]
+
+When you hit the 'Create pull request' button on this screen, the owner of the project you forked will get a notification that someone is suggesting a change and will link to a page that has all of this information on it.
+
+[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.
+====
+
+At this point, the project owner can look at the suggested change and merge it, reject it or comment on it. Let's say that he likes the idea, but would prefer a slightly longer time for the light to be off than on.
+
+Where this conversation may take place over email in the workflows presented in the previous chapter, on GitHub this happens online. The project owner can review the unified diff and leave a comment by clicking on any of the lines.
+
+.Pull Request line comment
+image::images/blink-3-seconds.png[PR line comment]
+
+They can also leave a general comment on the Pull Request. In <<_pr_discussion>> we can see an example of the project owner both commenting on a line of code and then leaving a general comment in the discussion section. You can see that the code comments are brought into the conversation as well.
+
+[[_pr_discussion]]
+.Pull Request discusson page
+image::images/blink-comment.png[PR discussion page]
+
+Now the contributor can see what they need to do in order to get their change accepted. Luckily this is also a very simple thing to do. Where over email you may have to re-roll your series and resubmit it to the mailing list, with GitHub you simply commit to the topic branch again and push.
+
+If the contributor does that then the project owner will get notified again and when they visit the page they will see that it's been addressed. In fact, since a line of code changed that had a comment on it, GitHub notices that and collapses the outdated diff.
+
+.Pull Request final
+image::images/blink-final.png[PR final]
+
+The other thing you'll notice is that GitHub checks to see if the Pull Request merges cleanly and provides a button to do the merge for you on the server. This button only shows up if you have write access to the repository and if you click it GitHub will perform a ``non-fast-forward'' merge, meaning that even if the merge *could* be a fast-forward, it will still create a merge commit.
+
+If you would prefer, you can simply pull the branch down and merge it locally. If you merge this branch into the `master` branch and push it to GitHub, the Pull Request will automatically be closed.
+
+This is the basic workflow that most GitHub projects use. Topic branches are created, Pull Requests are opened on them, a discussion ensues, possibly more work is done on the branch and eventually the request is either closed or merged.
+
+[NOTE]
+.Not Only Forks
+====
+It's important to note that you can also open a Pull Request between two branches in the same repository. If you're working on a feature with someone and you both have write access to the project, you can push a topic branch to the repository and open a Pull Request on it to the `master` branch of that same project to initiate the code review and discussion process. No forking neccesary.
+====

book/06-github/sections/github-flow.asc

@@ -0,0 +1,32 @@
+[[_github_orgs]]
+=== Organizations
+
+(((GitHub, organizations)))
+In addition to single-user accounts, GitHub has what are called Organizations.
+Organizational accounts have a namespace where projects exist, but most other things are different.
+These accounts represent a group of people with shared ownership of projects, and they provide tools to manage subgroups of those people.
+
+An organization is pretty easy to create; just click on the ``+'' icon at the top-right of any GitHub page, and select ``New organization'' from the menu.
+
+.The ``New organization'' menu item.
+image::images/neworg.png[The ``New organization'' menu item.]
+
+Follow the steps (a credit card is required, even for the free plan), and you'll soon be the owner of a brand-new organization.
+As an owner, when you fork a repository, you'll have the choice of forking it to your organization's namespace, and you automatically ``watch'' any new repository created under that organization.
+
+==== Teams
+
+Organizations are associated with inidividual people by way of teams, which are simply a set of individual user accounts.
+The power of teams comes with how they tie into other GitHub features.
+
+Organizations don't grant access to their repositories to _users_, they grant it to _teams_.
+For example, say your company has three repositories: `frontend`, `backend`, and `deployscripts`.
+You'd want your HTML/CSS/Javascript developers to have access to `frontend` and maybe `backend`, and your ops people to have access to `backend` and `deployscripts`.
+Teams make this easy, without having to tweak the settings for every single user.
+
+But that's not all teams are good for.
+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.
+
+A user can belong to any number of teams, so don't limit yourself to only access-control teams.
+Special-interest teams like `ux`, `css`, or `refactoring` are useful for certain kinds of questions, and others like `legal` and `colorblind` for an entirely different kind.