Do you have a contribution? We welcome contributions, but please ensure that you read the following information
before issuing a pull request. Also refer back to this document as a checklist before issuing your pull request.
This will save time for everyone.
If you don't understand what a pull request is, or how to submit one, please refer to the help documentation
provided by GitHub.
If you aren't sure if your contribution is needed or necessary, please visit the support forum before attempting to
submit a pull request or a ticket.
We require every commit to be tracked via our bug database. It is useful, before you get too far, that you have
checked that your issue isn't already known, otherwise addressed? If you think it is a valid defect or enhancement,
please open a new ticket before submitting your pull request.
If your desired contribution is more than a non-trivial fix, you should discuss it on the
contributor's mailing list. If you currently are not a member, you can request to be added.
We require all contributions, to be covered under the Dojo Foundation's Contributor License Agreement. This can
be done electronically and essentially ensures that you are making it clear that your contributions are your
contributions, you have the legal right to contribute and you are transferring the copyright of your works to the Dojo
Foundation.
If you are an unfamiliar contributor to the committer assessing your pull request, it is best to make it clear how
you are covered by a CLA in the notes of the pull request. The committer will verify your status.
If your GitHub user id you are submitting your pull request from differs from the Dojo Community ID or e-mail address
which you have signed your CLA under, you should specifically note what you have your CLA filed under (and for CCLA
that you are listed under your company's authorised contributors).
The following are the general steps you should follow in creating a pull request. Subsequent pull requests only need
to follow step 3 and beyond:
Note: While there are other ways to accomplish the steps using other tools, the examples here will assume the most
actions will be performed via the git command line.
When logged in to your GitHub account, and you are viewing one of the main repositories, you will see the Fork button.
Clicking this button will show you which repositories your can fork to. Choose your own account. Once the process
finishes, you will have your own repository that is "forked" from the official one.
Forking is a GitHub term and not a git term. Git is a wholly distributed source control system and simply worries
about local and remote repositories and allows you to manage your code against them. GitHub then adds this additional
layer of structure of how repositories can relate to each other.
Once you have successfully forked your repository, you will need to clone it locally to your machine:
$ git clone --recursive git@github.com:username/dojo.git
This will clone your fork to your current path in a directory named dojo.
It is important that you clone recursively for dojox, demos or utilbecause some of the code is contained in
submodules. You won't be able to submit your changes to the repositories that way though. If you are working on any of
these sub-projects, you should contact those project leads to see if their workflow differs.
You should also set up the upstream repository. This will allow you to take changes from the "main" repository
and merge them into your local clone and then push them to your GitHub fork:
$ cd dojo
$ git remote add upstream git@github.com:dojo/dojo.git
$ git fetch upstream
Then you can retrieve upstream changes and rebase on them into your code like this:
$ git pull --rebase upstream main
For more information on maintaining a fork, please see the GitHub Help article Fork a Repo and information on
rebasing from git.
The easiest workflow is to keep your main branch in sync with the upstream branch and do not locate any of your own
commits in that branch. When you want to work on a new feature, you then ensure you are on the main branch and create
a new branch from there. While the name of the branch can be anything, it can often be easy to use the ticket number
you might be working on. For example:
$ git checkout -b t12345 main
Switched to a new branch 't12345'
You will then be on the feature branch. You can verify what branch you are on like this:
$ git status
# On branch t12345
nothing to commit, working directory clean
Now you just need to make your changes. Once you have finished your changes (and tested them) you need to commit them
to your local repository (assuming you have staged your changes for committing):
$ git status
# On branch t12345
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: somefile.js
#
$ git commit -m "Corrects some defect, fixes #12345, refs #12346"
[t12345 0000000] Corrects some defect, fixes #12345, refs #12346
1 file changed, 2 insertions(+), 2 deletions(-)
If you have been working on your contribution for a while, the upstream repository may have changed. You may want to
ensure your work is on top of the latest changes so your pull request can be applied cleanly:
$ git pull --rebase upstream main
When you are ready to push your commit to your GitHub repository for the first time on this branch you would do the
following:
$ git push -u origin t12345
After the first time, you simply need to do:
$ git push
In order to have your commits merged into the main repository, you need to create a pull request. The instructions for
this can be found in the GitHub Help Article Creating a Pull Request. Essentially you do the following:
Send Pull RequestYou will get notified about the status of your pull request based on your GitHub settings.
Your request will be reviewed. It may be merged directly, or you may receive feedback or questions on your pull
request.
Having your contribution accepted is more than just the mechanics of getting your contribution into a pull request,
there are several other things that are expected when contributing to the Dojo Toolkit which are covered below.
Dojo has a very specific coding style. All pull requests should adhere to this.
Dojo has an inline API documentation called DojoDoc. Any pull request should ensure it has updated the inline
documentation appropriately or added the appropriate inline documentation.
If the pull request changes the functional behaviour or is fixing a defect, the unit test cases should be modified to
reflect this. The committer reviewing your pull request is likely to request the appropriate changes in the test
cases. Dojo utilises its own test harness called D.O.H. and is available as part of the dojo/util repository.
It is expected that you will have tested your changes against the existing test cases and appropriate platforms prior to
submitting your pull request.
All of your submissions are licensed under a dual "New" BSD/AFL license.
Unless you have been working with contributing to Dojo for a while, expect a significant amount of feedback on your
pull requests. We are a very passionate community and even the committers often will provide robust feedback to each
other about their code. Don't be offended by such feedback or feel that your contributions aren't welcome, it is just
that we are quite passionate and Dojo has a long history with many things that are the "Dojo-way" which may be
unfamiliar to those who are just starting to contribute.