From 6887a0f57307820b097b51aee952c555bcf69024 Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Fri, 20 Jan 2017 12:29:59 -0500 Subject: lib: Upgrade Dojo and Dijit from 1.8.3 to 1.12.1 The itemNode and expandoNode elements have changed from img to span (https://bugs.dojotoolkit.org/ticket/16699), so we now put our tree icons inside them rather than replacing them. Signed-off-by: Anders Kaseorg --- lib/dijit/CONTRIBUTING.md | 226 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 lib/dijit/CONTRIBUTING.md (limited to 'lib/dijit/CONTRIBUTING.md') diff --git a/lib/dijit/CONTRIBUTING.md b/lib/dijit/CONTRIBUTING.md new file mode 100644 index 000000000..12064098b --- /dev/null +++ b/lib/dijit/CONTRIBUTING.md @@ -0,0 +1,226 @@ +_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._ + +# Before You Start + +## Understanding the Basics + +If you don't understand what a *pull request* is, or how to submit one, please refer to the [help documentation][] +provided by GitHub. + +## Is It Really a Support Issue + +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. + +## Search Dojo Toolkit's Bug Database + +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. + +## Discuss Non-Trivial Contributions with the Committers + +If your desired contribution is more than a non-trivial fix, you should discuss it on the +[contributor's mailing list][dojo-contrib]. If you currently are not a member, you can request to be added. + +## Contributor License Agreement + +We require all contributions, to be covered under the JS Foundation's [Contributor License Agreement][cla]. 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. A bot will verify your status. + +If your GitHub user id you are submitting your pull request from differs from the e-mail address +which you have signed your CLA under, you should specifically note what you have your CLA filed under. + +# Submitting a Pull Request + +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: + +1. Fork the repository on GitHub +2. Clone the forked repository to your machine +3. Create a "feature" branch in your local repository +4. Make your changes and commit them to your local repository +5. Rebase and push your commits to your GitHub remote fork/repository +6. Issue a Pull Request to the official repository +7. Your Pull Request is reviewed by a committer and merged into the repository + +*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. + +## 1. Fork the Repository + +When logged into 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 GitHub 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. + +## 2. Clone the Forked Repository + +Once you have successfully forked your repository, you will need to clone it locally to your machine: + +```bash +$ git clone --recursive git@github.com:username/dijit.git +``` + +This will clone your fork to your current path in a directory named `dijit`. + +It is important that you clone recursively for ``dojox``, ``demos`` or ``util``because 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 setup the `upstream` repository. This will allow you to take changes from the "master" repository +and merge them into your local clone and then push them to your GitHub fork: + +```bash +$ cd dojo +$ git remote add upstream git@github.com:dojo/dijit.git +$ git fetch upstream +``` + +Then you can retrieve upstream changes and rebase on them into your code like this: + +```bash +$ git pull --rebase upstream master +``` + +For more information on maintaining a fork, please see the GitHub Help article [Fork a Repo][] and information on +[rebasing][] from git. + +## 3. Create a Branch + +The easiest workflow is to keep your master 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 master 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: + +```bash +$ git checkout -b t12345 master +Switched to a new branch 't12345' +``` + +You will then be on the feature branch. You can verify what branch you are on like this: + +```bash +$ git status +# On branch t12345 +nothing to commit, working directory clean +``` + +## 4. Make Changes and Commit + +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): + +```bash +$ git status +# On branch t12345 +# Changes to be committed: +# (use "git reset HEAD ..." 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(-) +``` + +## 5. Rebase and Push Changes + +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: + +```bash +$ git pull --rebase upstream master +``` + +When you are ready to push your commit to your GitHub repository for the first time on this branch you would do the +following: + +```bash +$ git push -u origin t12345 +``` + +After the first time, you simply need to do: + +```bash +$ git push +``` + +## 6. Issue a Pull Request + +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: + +1. Go to the site for your repository. +2. Click the Pull Request button. +3. Select the feature branch from your repository. +4. Enter a title and description of your pull request mentioning the corresponding [bug database][] ticket in the description. +5. Review the commit and files changed tabs. +6. Click `Send Pull Request` + +You will get notified about the status of your pull request based on your GitHub settings. + +## 7. Request is Reviewed and Merged + +Your request will be reviewed. It may be merged directly, or you may receive feedback or questions on your pull +request. + +# What Makes a Successful 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. + +## Coding Style and Linting + +Dojo has a very specific [coding style][styleguide]. All pull requests should adhere to this. + +## Inline Documentation + +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. + +## Test Cases + +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 [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. + +It is expected that you will have tested your changes against the existing test cases and appropriate platforms prior to +submitting your pull request. + +## Licensing + +All of your submissions are licensed under a dual "New" BSD/AFL license. + +## Expect Discussion and Rework + +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. + +[help documentation]: http://help.github.com/send-pull-requests +[bug database]: http://bugs.dojotoolkit.org/ +[support forum]: http://dojotoolkit.org/community/ +[dojo-contrib]: http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors +[cla]: http://js.foundation/CLA +[Creating a Pull Request]: https://help.github.com/articles/creating-a-pull-request +[Fork a Repo]: https://help.github.com/articles/fork-a-repo +[Intern]: http://theintern.io/ +[styleguide]: http://dojotoolkit.org/reference-guide/developer/styleguide.html +[DojoDoc]: http://dojotoolkit.org/reference-guide/developer/markup.html +[D.O.H.]: http://dojotoolkit.org/reference-guide/util/doh.html +[dojo/util]: https://github.com/dojo/util +[interactive rebase]: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages +[rebasing]: http://git-scm.com/book/en/Git-Branching-Rebasing -- cgit v1.2.3