lib/dijit/CONTRIBUTING.md

   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