]>
Commit | Line | Data |
---|---|---|
6887a0f5 AK |
1 | _Do you have a contribution? We welcome contributions, but please ensure that you read the following information |
2 | before issuing a pull request. Also refer back to this document as a checklist before issuing your pull request. | |
3 | This will save time for everyone._ | |
4 | ||
5 | # Before You Start | |
6 | ||
7 | ## Understanding the Basics | |
8 | ||
9 | If you don't understand what a *pull request* is, or how to submit one, please refer to the [help documentation][] | |
10 | provided by GitHub. | |
11 | ||
12 | ## Is It Really a Support Issue | |
13 | ||
14 | If you aren't sure if your contribution is needed or necessary, please visit the [support forum][] before attempting to | |
15 | submit a pull request or a ticket. | |
16 | ||
17 | ## Search Dojo Toolkit's Bug Database | |
18 | ||
19 | We require every commit to be tracked via our [bug database][]. It is useful, before you get too far, that you have | |
20 | checked that your issue isn't already known, otherwise addressed? If you think it is a valid defect or enhancement, | |
21 | please open a new ticket before submitting your pull request. | |
22 | ||
23 | ## Discuss Non-Trivial Contributions with the Committers | |
24 | ||
25 | If your desired contribution is more than a non-trivial fix, you should discuss it on the | |
26 | [contributor's mailing list][dojo-contrib]. If you currently are not a member, you can request to be added. | |
27 | ||
28 | ## Contributor License Agreement | |
29 | ||
30 | We require all contributions, to be covered under the JS Foundation's [Contributor License Agreement][cla]. This can | |
31 | be done electronically and essentially ensures that you are making it clear that your contributions are your | |
32 | contributions, you have the legal right to contribute and you are transferring the copyright of your works to the Dojo | |
33 | Foundation. | |
34 | ||
35 | If you are an unfamiliar contributor to the committer assessing your pull request, it is best to make it clear how | |
36 | you are covered by a CLA in the notes of the pull request. A bot will verify your status. | |
37 | ||
38 | If your GitHub user id you are submitting your pull request from differs from the e-mail address | |
39 | which you have signed your CLA under, you should specifically note what you have your CLA filed under. | |
40 | ||
41 | # Submitting a Pull Request | |
42 | ||
43 | The following are the general steps you should follow in creating a pull request. Subsequent pull requests only need | |
44 | to follow step 3 and beyond: | |
45 | ||
46 | 1. Fork the repository on GitHub | |
47 | 2. Clone the forked repository to your machine | |
48 | 3. Create a "feature" branch in your local repository | |
49 | 4. Make your changes and commit them to your local repository | |
50 | 5. Rebase and push your commits to your GitHub remote fork/repository | |
51 | 6. Issue a Pull Request to the official repository | |
52 | 7. Your Pull Request is reviewed by a committer and merged into the repository | |
53 | ||
54 | *Note* While there are other ways to accomplish the steps using other tools, the examples here will assume the most | |
55 | actions will be performed via the `git` command line. | |
56 | ||
57 | ## 1. Fork the Repository | |
58 | ||
59 | When logged into your GitHub account, and you are viewing one of the main repositories, you will see the *Fork* button. | |
60 | Clicking this button will show you which repositories your can fork to. Choose your own account. Once the process | |
61 | finishes, you will have your own repository that is "forked" from the GitHub one. | |
62 | ||
63 | Forking is a GitHub term and not a git term. Git is a wholly distributed source control system and simply worries | |
64 | about local and remote repositories and allows you to manage your code against them. GitHub then adds this additional | |
65 | layer of structure of how repositories can relate to each other. | |
66 | ||
67 | ## 2. Clone the Forked Repository | |
68 | ||
69 | Once you have successfully forked your repository, you will need to clone it locally to your machine: | |
70 | ||
71 | ```bash | |
72 | $ git clone --recursive git@github.com:username/dijit.git | |
73 | ``` | |
74 | ||
75 | This will clone your fork to your current path in a directory named `dijit`. | |
76 | ||
77 | It is important that you clone recursively for ``dojox``, ``demos`` or ``util``because some of the code is contained in | |
78 | submodules. You won't be able to submit your changes to the repositories that way though. If you are working on any of | |
79 | these sub-projects, you should contact those project leads to see if their workflow differs. | |
80 | ||
81 | You should also setup the `upstream` repository. This will allow you to take changes from the "master" repository | |
82 | and merge them into your local clone and then push them to your GitHub fork: | |
83 | ||
84 | ```bash | |
85 | $ cd dojo | |
86 | $ git remote add upstream git@github.com:dojo/dijit.git | |
87 | $ git fetch upstream | |
88 | ``` | |
89 | ||
90 | Then you can retrieve upstream changes and rebase on them into your code like this: | |
91 | ||
92 | ```bash | |
93 | $ git pull --rebase upstream master | |
94 | ``` | |
95 | ||
96 | For more information on maintaining a fork, please see the GitHub Help article [Fork a Repo][] and information on | |
97 | [rebasing][] from git. | |
98 | ||
99 | ## 3. Create a Branch | |
100 | ||
101 | The easiest workflow is to keep your master branch in sync with the upstream branch and do not locate any of your own | |
102 | commits in that branch. When you want to work on a new feature, you then ensure you are on the master branch and create | |
103 | a new branch from there. While the name of the branch can be anything, it can often be easy to use the ticket number | |
104 | you might be working on. For example: | |
105 | ||
106 | ```bash | |
107 | $ git checkout -b t12345 master | |
108 | Switched to a new branch 't12345' | |
109 | ``` | |
110 | ||
111 | You will then be on the feature branch. You can verify what branch you are on like this: | |
112 | ||
113 | ```bash | |
114 | $ git status | |
115 | # On branch t12345 | |
116 | nothing to commit, working directory clean | |
117 | ``` | |
118 | ||
119 | ## 4. Make Changes and Commit | |
120 | ||
121 | Now you just need to make your changes. Once you have finished your changes (and tested them) you need to commit them | |
122 | to your local repository (assuming you have staged your changes for committing): | |
123 | ||
124 | ```bash | |
125 | $ git status | |
126 | # On branch t12345 | |
127 | # Changes to be committed: | |
128 | # (use "git reset HEAD <file>..." to unstage) | |
129 | # | |
130 | # modified: somefile.js | |
131 | # | |
132 | $ git commit -m "Corrects some defect, fixes #12345, refs #12346" | |
133 | [t12345 0000000] Corrects some defect, fixes #12345, refs #12346 | |
134 | 1 file changed, 2 insertions(+), 2 deletions(-) | |
135 | ``` | |
136 | ||
137 | ## 5. Rebase and Push Changes | |
138 | ||
139 | If you have been working on your contribution for a while, the upstream repository may have changed. You may want to | |
140 | ensure your work is on top of the latest changes so your pull request can be applied cleanly: | |
141 | ||
142 | ```bash | |
143 | $ git pull --rebase upstream master | |
144 | ``` | |
145 | ||
146 | When you are ready to push your commit to your GitHub repository for the first time on this branch you would do the | |
147 | following: | |
148 | ||
149 | ```bash | |
150 | $ git push -u origin t12345 | |
151 | ``` | |
152 | ||
153 | After the first time, you simply need to do: | |
154 | ||
155 | ```bash | |
156 | $ git push | |
157 | ``` | |
158 | ||
159 | ## 6. Issue a Pull Request | |
160 | ||
161 | In order to have your commits merged into the main repository, you need to create a pull request. The instructions for | |
162 | this can be found in the GitHub Help Article [Creating a Pull Request][]. Essentially you do the following: | |
163 | ||
164 | 1. Go to the site for your repository. | |
165 | 2. Click the Pull Request button. | |
166 | 3. Select the feature branch from your repository. | |
167 | 4. Enter a title and description of your pull request mentioning the corresponding [bug database][] ticket in the description. | |
168 | 5. Review the commit and files changed tabs. | |
169 | 6. Click `Send Pull Request` | |
170 | ||
171 | You will get notified about the status of your pull request based on your GitHub settings. | |
172 | ||
173 | ## 7. Request is Reviewed and Merged | |
174 | ||
175 | Your request will be reviewed. It may be merged directly, or you may receive feedback or questions on your pull | |
176 | request. | |
177 | ||
178 | # What Makes a Successful Pull Request? | |
179 | ||
180 | Having your contribution accepted is more than just the mechanics of getting your contribution into a pull request, | |
181 | there are several other things that are expected when contributing to the Dojo Toolkit which are covered below. | |
182 | ||
183 | ## Coding Style and Linting | |
184 | ||
185 | Dojo has a very specific [coding style][styleguide]. All pull requests should adhere to this. | |
186 | ||
187 | ## Inline Documentation | |
188 | ||
189 | Dojo has an inline API documentation called [DojoDoc][]. Any pull request should ensure it has updated the inline | |
190 | documentation appropriately or added the appropriate inline documentation. | |
191 | ||
192 | ## Test Cases | |
193 | ||
194 | If the pull request changes the functional behaviour or is fixing a defect, the unit test cases should be modified to | |
195 | reflect this. The committer reviewing your pull request is likely to request the appropriate changes in the test | |
196 | cases. Dojo utilises [Intern][] for all new tests, and has legacy support for its previous generation test harness called [D.O.H.][] and is available as part of the [dojo/util][] repository. All new tests should be authored using Intern. | |
197 | ||
198 | It is expected that you will have tested your changes against the existing test cases and appropriate platforms prior to | |
199 | submitting your pull request. | |
200 | ||
201 | ## Licensing | |
202 | ||
203 | All of your submissions are licensed under a dual "New" BSD/AFL license. | |
204 | ||
205 | ## Expect Discussion and Rework | |
206 | ||
207 | Unless you have been working with contributing to Dojo for a while, expect a significant amount of feedback on your | |
208 | pull requests. We are a very passionate community and even the committers often will provide robust feedback to each | |
209 | other about their code. Don't be offended by such feedback or feel that your contributions aren't welcome, it is just | |
210 | that we are quite passionate and Dojo has a long history with many things that are the "Dojo-way" which may be | |
211 | unfamiliar to those who are just starting to contribute. | |
212 | ||
213 | [help documentation]: http://help.github.com/send-pull-requests | |
214 | [bug database]: http://bugs.dojotoolkit.org/ | |
215 | [support forum]: http://dojotoolkit.org/community/ | |
216 | [dojo-contrib]: http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors | |
217 | [cla]: http://js.foundation/CLA | |
218 | [Creating a Pull Request]: https://help.github.com/articles/creating-a-pull-request | |
219 | [Fork a Repo]: https://help.github.com/articles/fork-a-repo | |
220 | [Intern]: http://theintern.io/ | |
221 | [styleguide]: http://dojotoolkit.org/reference-guide/developer/styleguide.html | |
222 | [DojoDoc]: http://dojotoolkit.org/reference-guide/developer/markup.html | |
223 | [D.O.H.]: http://dojotoolkit.org/reference-guide/util/doh.html | |
224 | [dojo/util]: https://github.com/dojo/util | |
225 | [interactive rebase]: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages | |
226 | [rebasing]: http://git-scm.com/book/en/Git-Branching-Rebasing |