1_Do you have a contribution? We welcome contributions, but please ensure that you read the following information 2before issuing a pull request. Also refer back to this document as a checklist before issuing your pull request. 3This will save time for everyone._ 4 5# Before You Start 6 7## Understanding the Basics 8 9If you don't understand what a *pull request* is, or how to submit one, please refer to the [help documentation][] 10provided by GitHub. 11 12## Is It Really a Support Issue 13 14If you aren't sure if your contribution is needed or necessary, please visit the [support forum][] before attempting to 15submit a pull request or a ticket. 16 17## Search Dojo Toolkit's Bug Database 18 19We require every commit to be tracked via our [bug database][]. It is useful, before you get too far, that you have 20checked that your issue isn't already known, otherwise addressed? If you think it is a valid defect or enhancement, 21please open a new ticket before submitting your pull request. 22 23## Discuss Non-Trivial Contributions with the Committers 24 25If 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 30We require all contributions, to be covered under the JS Foundation's [Contributor License Agreement][cla]. This can 31be done electronically and essentially ensures that you are making it clear that your contributions are your 32contributions, you have the legal right to contribute and you are transferring the copyright of your works to the Dojo 33Foundation. 34 35If you are an unfamiliar contributor to the committer assessing your pull request, it is best to make it clear how 36you are covered by a CLA in the notes of the pull request. A bot will verify your status. 37 38If your GitHub user id you are submitting your pull request from differs from the e-mail address 39which you have signed your CLA under, you should specifically note what you have your CLA filed under. 40 41# Submitting a Pull Request 42 43The following are the general steps you should follow in creating a pull request. Subsequent pull requests only need 44to follow step 3 and beyond: 45 461. Fork the repository on GitHub 472. Clone the forked repository to your machine 483. Create a "feature" branch in your local repository 494. Make your changes and commit them to your local repository 505. Rebase and push your commits to your GitHub remote fork/repository 516. Issue a Pull Request to the official repository 527. 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 55actions will be performed via the `git` command line. 56 57## 1. Fork the Repository 58 59When logged in to your GitHub account, and you are viewing one of the main repositories, you will see the *Fork* button. 60Clicking this button will show you which organizations your can fork to. Choose your own account. Once the process 61finishes, you will have your own repository that is "forked" from the official one. 62 63Forking is a GitHub term and not a git term. Git is a wholly distributed source control system and simply worries 64about local and remote repositories and allows you to manage your code against them. GitHub then adds this additional 65layer of structure of how repositories can relate to each other. 66 67## 2. Clone the Forked Repository 68 69Once 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/dojo.git 73``` 74 75This will clone your fork to your current path in a directory named `dojo`. 76 77It is important that you clone recursively for ``dojox``, ``demos`` or ``util``because some of the code is contained in 78submodules. You won't be able to submit your changes to the repositories that way though. If you are working on any of 79these sub-projects, you should contact those project leads to see if their workflow differs. 80 81You should also set up the `upstream` repository. This will allow you to take changes from the "master" repository 82and 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/dojo.git 87$ git fetch upstream 88``` 89 90Then 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 96For 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 101The easiest workflow is to keep your master branch in sync with the upstream branch and do not locate any of your own 102commits in that branch. When you want to work on a new feature, you then ensure you are on the master branch and create 103a new branch from there. While the name of the branch can be anything, it can often be easy to use the ticket number 104you might be working on. For example: 105 106```bash 107$ git checkout -b t12345 master 108Switched to a new branch 't12345' 109``` 110 111You 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 116nothing to commit, working directory clean 117``` 118 119## 4. Make Changes and Commit 120 121Now you just need to make your changes. Once you have finished your changes (and tested them) you need to commit them 122to 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 139If you have been working on your contribution for a while, the upstream repository may have changed. You may want to 140ensure 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 146When you are ready to push your commit to your GitHub repository for the first time on this branch you would do the 147following: 148 149```bash 150$ git push -u origin t12345 151``` 152 153After the first time, you simply need to do: 154 155```bash 156$ git push 157``` 158 159## 6. Issue a Pull Request 160 161In order to have your commits merged into the main repository, you need to create a pull request. The instructions for 162this can be found in the GitHub Help Article [Creating a Pull Request][]. Essentially you do the following: 163 1641. Go to the site for your repository. 1652. Click the Pull Request button. 1663. Select the feature branch from your repository. 1674. Enter a title and description of your pull request mentioning the corresponding [bug database][] ticket in the description. 1685. Review the commit and files changed tabs. 1696. Click `Send Pull Request` 170 171You will get notified about the status of your pull request based on your GitHub settings. 172 173## 7. Request is Reviewed and Merged 174 175Your request will be reviewed. It may be merged directly, or you may receive feedback or questions on your pull 176request. 177 178# What Makes a Successful Pull Request? 179 180Having your contribution accepted is more than just the mechanics of getting your contribution into a pull request, 181there are several other things that are expected when contributing to the Dojo Toolkit which are covered below. 182 183## Coding Style and Linting 184 185Dojo has a very specific [coding style][styleguide]. All pull requests should adhere to this. 186 187## Inline Documentation 188 189Dojo has an inline API documentation called [DojoDoc][]. Any pull request should ensure it has updated the inline 190documentation appropriately or added the appropriate inline documentation. 191 192## Test Cases 193 194If the pull request changes the functional behaviour or is fixing a defect, the unit test cases should be modified to 195reflect this. The committer reviewing your pull request is likely to request the appropriate changes in the test 196cases. 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 198It is expected that you will have tested your changes against the existing test cases and appropriate platforms prior to 199submitting your pull request. 200 201## Licensing 202 203All of your submissions are licensed under a dual "New" BSD/AFL license. 204 205## Expect Discussion and Rework 206 207Unless you have been working with contributing to Dojo for a while, expect a significant amount of feedback on your 208pull requests. We are a very passionate community and even the committers often will provide robust feedback to each 209other about their code. Don't be offended by such feedback or feel that your contributions aren't welcome, it is just 210that we are quite passionate and Dojo has a long history with many things that are the "Dojo-way" which may be 211unfamiliar 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]: https://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 227