├── _config.yml
├── fork.png
├── pull.png
├── clone.png
├── pull2.png
├── pull3.png
├── assets
└── css
│ └── style.scss
├── LICENSE
├── _layouts
└── default.html
└── README.md
/_config.yml:
--------------------------------------------------------------------------------
1 | theme: jekyll-theme-cayman
2 | title: Git Workflow
3 |
--------------------------------------------------------------------------------
/fork.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/asmeurer/git-workflow/HEAD/fork.png
--------------------------------------------------------------------------------
/pull.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/asmeurer/git-workflow/HEAD/pull.png
--------------------------------------------------------------------------------
/clone.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/asmeurer/git-workflow/HEAD/clone.png
--------------------------------------------------------------------------------
/pull2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/asmeurer/git-workflow/HEAD/pull2.png
--------------------------------------------------------------------------------
/pull3.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/asmeurer/git-workflow/HEAD/pull3.png
--------------------------------------------------------------------------------
/assets/css/style.scss:
--------------------------------------------------------------------------------
1 | ---
2 | ---
3 |
4 | @import "{{ site.theme }}";
5 |
6 | // Reduce the height of the header
7 | .page-header {
8 | padding: 1rem 1rem;
9 | }
10 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2015 Aaron Meurer
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
23 |
--------------------------------------------------------------------------------
/_layouts/default.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | {{ page.title | default: site.title }}
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
15 | {% if site.show_downloads %}
16 | Download .zip
17 | Download .tar.gz
18 | {% endif %}
19 |
20 |
21 |
22 | {{ content }}
23 |
24 |
30 |
31 |
32 | {% if site.google_analytics %}
33 |
42 | {% endif %}
43 |
44 |
45 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Git workflow
2 |
3 | This document describes the git workflow that should be used when contributing
4 | to open source projects on GitHub. It assumes a very basic understanding of
5 | git (commits, branches, etc.) using the command line.
6 |
7 | *Note: This workflow is designed for open source (i.e., public)
8 | repositories. The workflow for private repositories may be slightly different,
9 | in particular, the repository's team may prefer for you to not fork the repo
10 | but rather push branches to it directly (although note that GitHub does allow
11 | you to fork private repositories that you have push access to and keeps the
12 | fork private).*
13 |
14 | For this document, we will suppose that you want to contribute a patch to
15 | [sympy/sympy](https://github.com/sympy/sympy).
16 |
17 | **NOTE: If you want to test out this guide without making an
18 | actual fix, please test against THIS REPO (`asmeurer/git-workflow`). Do not
19 | make a pull request against `sympy/sympy` unless you are making an actual
20 | change.**
21 |
22 | ## Cloning and forking the repository
23 |
24 | **Note: The steps in this section only need to be performed once per
25 | repository (e.g., if you contribute a second change to sympy/sympy, you would
26 | not need to repeat them, but if you contribute to
27 | [sympy/sympy-live](https://github.com/sympy/sympy-live) you will need to
28 | repeat them for that repository).**
29 |
30 | 1. **Clone the repository.** Click the green "Clone or download" button ①,
31 | and copy the url ② and type
32 |
33 | git clone clone-url
34 |
35 | at the terminal. Replace *`clone-url`* with the url that has been copied to
36 | your clipboard. For sympy/sympy, it will be
37 | `git@github.com:sympy/sympy.git`. If you have not set up your ssh keys with
38 | GitHub, use the https url by first clicking the `https` button ③.
40 |
41 | 
42 |
43 | *Note: It is important that you clone from the repo you are contributing
44 | to (like sympy/sympy),* not *your fork of the repo.*
45 |
46 | 2. **Fork the repo on GitHub to your personal account.** Click the `Fork`
47 | button on the sympy/sympy page.
48 |
49 | 
50 |
51 | If you are presented with a list of organizations, click on your GitHub
52 | username.
53 |
54 | 3. **Add your fork as a remote.** This remote will be named after your github
55 | username. Go to the fork of your repository, in this case,
56 | https://github.com/your-username/sympy (replace *`your-username`* with
57 | your GitHub username), and copy the clone url as in step 1. `cd` to your
58 | clone from step 1 and run
59 |
60 |
61 | git remote add your-github-usernamefork-url
62 |
63 |
64 | (replace *`your-github-username`* with your GitHub username and
65 | *`fork-url`* with the url that was copied to your clipboard). You will be
66 | able to tell it is your fork url because it will have your GitHub username
67 | in it. For instance, if your username is `github_user`, you would run the
68 | command `git remote add github_user git@github.com:github_user/sympy.git`.
69 |
70 | Remember, the above three steps only need to be performed once per
71 | repository. Once you have cloned and forked a repository once, there is no
72 | need to clone or fork it again.
73 |
74 | ## Making changes
75 |
76 | Before you make any changes, you should make a branch. Remember to **never
77 | commit to master**. The command `git status` will tell you what branch you are
78 | on. I recommend putting the git branch in your command prompt, so that you
79 | will always know what branch you are on. See
80 | [this guide](http://stackoverflow.com/a/24716445/161801) on how to do this.
81 |
82 | It is important that you never commit to master because master will be the
83 | branch that you pull upstream changes from (e.g., changes from
84 | sympy/sympy).
85 |
86 | 1. **Update master.** Before you make any changes, first checkout master
87 |
88 | ```
89 | git checkout master
90 | ```
91 |
92 | and pull in the latest changes
93 |
94 | ```
95 | git pull
96 | ```
97 |
98 | This will make it so that your changes are against the very latest master,
99 | which will reduce the likelihood of merge conflicts due to your changes
100 | conflicting with changes made by someone else.
101 |
102 | 2. **Create a branch.** Once you have done this, create a new branch. You
103 | should make a branch name that is short, descriptive, and unique. Some
104 | examples of good branch names are `fix-install`, `docs-cleanup`, and
105 | `add-travis-ci`. Some examples of bad branch names are `feature`, `fix`,
106 | and `patch`. The branch name choice is not too important, so don't stress
107 | over it, but it is what people will use to reference your changes if they
108 | want to pull them down on their own computers to test them, so a good name
109 | will make it easier for others to understand what your branch does. In this
110 | example, the branch name is `fix-install`.
111 |
112 | To create the branch, run
113 |
114 |
115 | git checkout -b branch-name
116 |
117 |
118 | (replace *`branch-name`* with the branch name you chose). This will create a
119 | new branch and check it out. You can verify this with `git status`.
120 |
121 | 3. **Make your changes and commit them.** Once you have created your branch,
122 | make your changes and commit them. Remember to keep your commits atomic,
123 | that is, each commit should represent a single unit of change. Also,
124 | remember to write helpful commit messages, so that someone can understand
125 | what the commit does just from reading the message without having to read
126 | the diff.
127 |
128 | For example, at the command line, this might look like
129 |
130 |
133 |
134 | This will open an editor where you can write your commit message.
135 |
136 | 4. **Push up your changes.** Push your changes to your fork. Do this by
137 | running
138 |
139 |
140 | git push your-github-usernamebranch-name
141 |
142 |
143 | (replace *`your-github-username`* with your GitHub username and
144 | *`branch-name`* with the name of the branch).
145 |
146 | 5. **Make a pull request.** If you then go to your fork on GitHub, you should
147 | see a button to create a pull request from your branch. It will look
148 | something like this:
149 |
150 | 
151 |
152 | If you do not see this, go to the GitHub page for your fork ①, select the branch from the branch popup ② and click the pull request button ③.
156 |
157 | 
158 |
159 | Once doing this, you will be presented with a page. This page will show you
160 | the diff of the changes. Double check them to make sure you are making a
161 | pull request against the right branch.
162 |
163 | Things to check here are that the base fork is the upstream repo ① (in this case, sympy/sympy) and the branch for the
165 | upstream repo is master, and that the head fork is your fork ② and the branch is the branch you wish to make the
167 | pull request from.
168 |
169 | Enter a descriptive title in the title field ③.
170 | This is very important, as it is what will show up in the pull request
171 | listing and in email notifications to the people in the repo. Pull requests
172 | with undescriptive titles are more likely to be passed by. If the pull
173 | request fixes an issue, I recommend putting the issue number in the pull
174 | request description ④, not the title. People
175 | generally do not know issues by number, so a pull request that is just
176 | titled "fix for issue #1234" is more likely to be passed by, as it is
177 | unclear what it does from the title.
178 |
179 | If there is more description or discussion about the pull request than
180 | what fits in the title field use the description field ④.
182 |
183 | If the pull request fixes an issue, you can add "fixes #**1234**" (replace
184 | **1234** with the actual issue number) in the pull request description ④. This exact format, "fixes #**1234**" is important, as
186 | it will cause GitHub to automatically close the issue when the pull request
187 | is merged.
188 |
189 | Once you are done, click the "create pull request" button ⑤.
191 |
192 | 
193 |
194 | 6. **Pushing additional changes**. Once you have created the pull request, it
195 | will likely be reviewed and some additional fixes will be necessary. **Do
196 | not create a new pull request.** Rather, simply make more commits to your
197 | branch and push them up as in steps 3 and 4. They will be added to the pull
198 | request automatically. Note that although GitHub does notify people when
199 | you push new changes to a branch, many people have these notifications
200 | disabled as they can be quite noisy. So it is a good idea to make a comment
201 | on the pull request whenever you do so to notify people that it is ready to
202 | be reviewed again.
203 |
204 | Once the pull request has been reviewed successfully, someone with push access
205 | to the main repository will merge it in. At this point you are done. You can
206 | checkout master and pull as described in step 1 and your changes should be
207 | there.
208 |
209 | ## Important points
210 |
211 | The important things to remember from this document are
212 |
213 | 1. You only need to clone and fork once per repository.
214 |
215 | 2. Always clone from the main repository and add your fork as a remote.
216 |
217 | 3. Never commit to master. Create a branch and commit to it.
218 |
219 | 4. Use `git status` often to check what branch you are on and see if you have
220 | any uncommitted changes.
221 |
222 | 5. Be descriptive in your branch names, commit messages, and pull request
223 | title and descriptions.
224 |
225 | 6. Once you have a pull request for a branch, you can push additional changes
226 | to the same branch and they will be added to the pull request
227 | automatically. You should never create a new pull request for the same
228 | branch.
229 |
230 | 7. Comment on the pull request when you want people to know that you have
231 | pushed new changes. Although GitHub does notify people of commit pushes,
232 | people are more likely notice your changes if you leave a comment.
233 |
--------------------------------------------------------------------------------