From cf28c3b65270ae40c9450b916d2453c21a021c24 Mon Sep 17 00:00:00 2001 From: Kaartic Sivaraam Date: Thu, 19 Jan 2017 13:34:03 +0530 Subject: [PATCH 1/2] Added a few changes to the GitHub chapter (chap. no.-6) * corrected the first line of the chapter to prevent the over stress about GitHub * changed a sentence to make it read better * added "forking" to the GitHub workflow * retitled a section from "Markdown" to "GitHub Flavored Markdown" and reduced the level of sections under the latter section by 1 as, much wasn't told about Markdown in general * changed the image referenced to one that's easier to see * corrected the sentence about the protocol specified * retitled a section from "Hooks" to "Services and Hooks" as it had subsections about both --- book/06-github/1-github.asc | 2 +- book/06-github/sections/2-contributing.asc | 33 +++++++++++----------- book/06-github/sections/3-maintaining.asc | 6 ++-- book/06-github/sections/5-scripting.asc | 2 +- 4 files changed, 21 insertions(+), 22 deletions(-) diff --git a/book/06-github/1-github.asc b/book/06-github/1-github.asc index ecd727a81..417c28f42 100644 --- a/book/06-github/1-github.asc +++ b/book/06-github/1-github.asc @@ -2,7 +2,7 @@ == GitHub (((GitHub))) -GitHub is the single largest host for Git repositories, and is the central point of collaboration for millions of developers and projects. +GitHub is one of the largest host for Git repositories, and is the central point of collaboration for millions of developers and projects. A large percentage of all Git repositories are hosted on GitHub, and many open-source projects use it for Git hosting, issue tracking, code review, and other things. So while it's not a direct part of the Git open source project, there's a good chance that you'll want or need to interact with GitHub at some point while using Git professionally. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 793fd6906..1426633a6 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -6,7 +6,7 @@ Now that our account is set up, let's walk through some details that could be us (((forking))) If you want to contribute to an existing project to which you don’t have push access, you can ``fork'' the project. -What this means is that GitHub will make a copy of the project that is entirely yours; it lives in your user's namespace, and you can push to it. +When you ``fork'' a project, GitHub will make a copy of the project that is entirely yours; it lives in your namespace, and you can push to it. [NOTE] ==== @@ -36,12 +36,13 @@ 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. Push this branch to your GitHub project. -4. Open a Pull Request on GitHub. -5. Discuss, and optionally continue committing. -6. The project owner merges or closes the Pull Request. +1. Fork the project +2. Create a topic branch from `master`. +3. Make some commits to improve the project. +4. Push this branch to your GitHub project. +5. Open a Pull Request on GitHub. +6. Discuss, and optionally continue committing. +7. 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. @@ -285,21 +286,19 @@ image::images/mentions-03-closed.png[PR closed] In addition to issue numbers, you can also reference a specific commit by SHA-1. You have to specify a full 40 character SHA-1, but if GitHub sees that in a comment, it will link directly to the commit. Again, you can reference commits in forks or other repositories in the same way you did with issues. -==== Markdown +==== GitHub Flavored Markdown Linking to other Issues is just the beginning of interesting things you can do with almost any text box on GitHub. In Issue and Pull Request descriptions, comments, code comments and more, you can use what is called ``GitHub Flavored Markdown''. Markdown is like writing in plain text but which is rendered richly. See <<_example_markdown>> for an example of how comments or text can be written and then rendered using Markdown. [[_example_markdown]] -.An example of Markdown as written and as rendered. +.An example of GitHub Flavored Markdown as written and as rendered. image::images/markdown-01-example.png[Example Markdown] -===== GitHub Flavored Markdown - The GitHub flavor of Markdown adds more things you can do beyond the basic Markdown syntax. These can all be really useful when creating useful Pull Request or Issue comments or descriptions. -====== Task Lists +===== Task Lists The first really useful GitHub specific Markdown feature, especially for use in Pull Requests, is the Task List. A task list is a list of checkboxes of things you want to get done. Putting them into an Issue or Pull Request normally indicates things that you want to get done before you consider the item complete. @@ -328,7 +327,7 @@ image::images/markdown-03-task-summary.png[Example Task List] These are incredibly useful when you open a Pull Request early and use it to track your progress through the implementation of the feature. -====== Code Snippets +===== Code Snippets You can also add code snippets to comments. This is especially useful if you want to present something that you _could_ try to do before actually implementing it as a commit on your branch. This is also often used to add example code of what is not working or what this Pull Request could implement. @@ -350,7 +349,7 @@ If you add a language name like we did there with 'java', GitHub will also try t .Rendered fenced code example. image::images/markdown-04-fenced-code.png[Rendered fenced code] -====== Quoting +===== 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. @@ -370,7 +369,7 @@ Once rendered, the comment will look like <<_md_quote>>. .Rendered quoting example. image::images/markdown-05-quote.png[Rendered quoting] -====== Emoji +===== Emoji Finally, you can also use emoji in your comments. This is actually used quite extensively in comments you see on many GitHub Issues and Pull Requests. There is even an emoji helper in GitHub. If you are typing a comment and you start with a `:` character, an autocompleter will help you find what you're looking for. @@ -407,7 +406,7 @@ There are actually quite a number of web services that make use of emoji charact http://www.emoji-cheat-sheet.com ==== -====== Images +===== Images This isn't technically GitHub Flavored Markdown, but it is incredibly useful. In addition to adding Markdown image links to comments, which can be difficult to find and embed URLs for, GitHub allows you to drag and drop images into text areas to embed them. @@ -415,4 +414,4 @@ This isn't technically GitHub Flavored Markdown, but it is incredibly useful. In .Drag and drop images to upload them and auto-embed them. image::images/markdown-08-drag-drop.png[Drag and drop images] -If you look back at <<_pr_references>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. +If you at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index 8ca6803ee..5612f874a 100644 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -27,14 +27,14 @@ Since you have no code there yet, GitHub will show you instructions for how to c We won't belabor this here; if you need a refresher, check out <<_git_basics_chapter>>. Now that your project is hosted on GitHub, you can give the URL to anyone you want to share your project with. -Every project on GitHub is accessible over HTTP as `https://github.com//`, and over SSH as `git@github.com:/`. +Every project on GitHub is accessible over HTTPS as `https://github.com//`, and over SSH as `git@github.com:/`. Git can fetch from and push to both of these URLs, but they are access-controlled based on the credentials of the user connecting to them. [NOTE] ==== -It is often preferable to share the HTTP based URL for a public project, since the user does not have to have a GitHub account to access it for cloning. +It is often preferable to share the HTTPS based URL for a public project, since the user does not have to have a GitHub account to access it for cloning. Users will have to have an account and an uploaded SSH key to access your project if you give them the SSH URL. -The HTTP one is also exactly the same URL they would paste into a browser to view the project there. +The HTTPS one is also exactly the same URL they would paste into a browser to view the project there. ==== ==== Adding Collaborators diff --git a/book/06-github/sections/5-scripting.asc b/book/06-github/sections/5-scripting.asc index 2d23d6e51..6bfb16e77 100644 --- a/book/06-github/sections/5-scripting.asc +++ b/book/06-github/sections/5-scripting.asc @@ -5,7 +5,7 @@ So now we've covered all of the major features and workflows of GitHub, but any Luckily for us, GitHub is really quite hackable in many ways. In this section we'll cover how to use the GitHub hooks system and its API to make GitHub work how we want it to. -==== Hooks +==== Services and Hooks The Hooks and Services section of GitHub repository administration is the easiest way to have GitHub interact with external systems. From 55ab559b5bc0626285e66834623d8c0a89f956a8 Mon Sep 17 00:00:00 2001 From: Kaartic Sivaraam Date: Mon, 23 Jan 2017 18:09:53 +0530 Subject: [PATCH 2/2] corrected mistakes that resulted from the previous commit * changed back the first sentence to it's original form * added back a word that was deleted by mistake --- book/06-github/1-github.asc | 2 +- book/06-github/sections/2-contributing.asc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/06-github/1-github.asc b/book/06-github/1-github.asc index 417c28f42..ecd727a81 100644 --- a/book/06-github/1-github.asc +++ b/book/06-github/1-github.asc @@ -2,7 +2,7 @@ == GitHub (((GitHub))) -GitHub is one of the largest host for Git repositories, and is the central point of collaboration for millions of developers and projects. +GitHub is the single largest host for Git repositories, and is the central point of collaboration for millions of developers and projects. A large percentage of all Git repositories are hosted on GitHub, and many open-source projects use it for Git hosting, issue tracking, code review, and other things. So while it's not a direct part of the Git open source project, there's a good chance that you'll want or need to interact with GitHub at some point while using Git professionally. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 1426633a6..6847ece4c 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -414,4 +414,4 @@ This isn't technically GitHub Flavored Markdown, but it is incredibly useful. In .Drag and drop images to upload them and auto-embed them. image::images/markdown-08-drag-drop.png[Drag and drop images] -If you at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub. +If you look at <<_md_drag>>, you can see a small ``Parsed as Markdown'' hint above the text area. Clicking on that will give you a full cheat sheet of everything you can do with Markdown on GitHub.