Dojo Development Workflow on GitHub

Dojo Development Workflow on GitHub

DRAFT - This is not valid yet

This document will provide guidelines for the Dojo Toolkit workflow on GitHub. As we will no longer be using SVN, it is important to adjust our workflow to match to GitHub.

The Main Components

The main GitHub Repositories for the Dojo 1.X code are:

• dojo/dojo
• dojo/djijit
• dojo/dojox
• dojo/util

You will need a valid GitHub user account. This can be tied to your Dojo Foundation user account if not already by contacting the appropriate project lead.

You will need the appropriate tools to manage your GitHub code. There are a few choices, but the two main ones are the standard git command line or the GitHub GUI:

• git
• GitHub Mac
• GitHub Windows

The examples in this document though will focus around using the git command line interface. If you need help setting up git to work against your GitHub account, please see the GitHub Help Article about the topic.

You also should be aware we continue to use bugs.dojotoolkit.org for ticket management. While GitHub issues have improved, they still do not give us sufficient features to be able to manage the code as we would like.

Individual Workflow

As an individual contributor or committer, the workflow is as follows:

1. Fork the repository on GitHub
2. Clone your forked repository on your machine
3. Create a "feature" branch on your local repository
4. Make your changes and commit them to your local repository
5. Push your commits to your GitHub fork/remote repository
6. Issue a Pull Request to the "upstream" repository
7. Your Pull Request is reviewed by a committer and merged into the repository

For maintainers of components of the toolkit, the following workflow may be used:

1. Clone the main repository from GitHub
2. Make your changes and commit them to your local repository
3. Push your commits to the main repository

Caution should be used when following this shorter workflow. Pull requests offer an opportunity for developers to have their code reviewed and tested before landing in the main repository. Large changes should generally follow the first workflow, while smaller changes can follow the second workflow. Please exercise caution with the second workflow and ensure commits have been fully tested before pushing. It is also very important that your commit messages include the appropriate ticket data. Normally this is added when the pull request is closed and signed off on GitHub.

Forking on GitHub

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.

Cloning Your Fork

Once you have successfully forked your repository, you will need to clone it locally to your machine:

$ git clone --recursive https://github.com/username/dojo.git

This will clone your fork to your current path in a directory named dojo.

You can also use the SSH URI for your repository (e.g. [email protected]:username/dojo.git) if you have configured SSH properly with your command line git. It is important that you clone recursively for dojox 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:

$ cd dojo
$ git remote add upstream https://github.com/dojo/dojo.git
$ git fetch upstream

Then you can retrieve upstream changes and merge them into your code like this:

$ git fetch upstream
$ git merge upstream/master

Please be aware though, that often times, if you have made changes that make it impossible to cleanly apply the upstream changes this will result in a new commit to merge these. If you provide a pull request that contains these unnecessary commits it may get rejected.

For more information on maintaining a for, please see the GitHub Help article Fork a Repo.

Creating a Feature 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:

$ git branch t12345
$ git checkout t12345
Switched to 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

Or alternatively:

$ git branch
  master
* t12345

Making Your Changes and Committing

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(-)

When you are ready to push your commits to your GitHub repository, you would then:

$ git push

But if you are using pushing a branch for the first time, you might get something like the following, where you need to identify how you want the remote branch named:

$ git push
fatal: The current branch t12345 has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream t12345 t12345

Issuing 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.
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.

Merging a Pull Request

If you are a committer/maintainer of the repositories, you can merge pull requests. The merging of pull requests is covered in the GitHub Help Article Merging a Pull Request which provides not only the instructions of merging the pull request on-line, but how to perform the merge on your local clone and potentially resolve conflicts before merging.

Please ensure though that the commit message for the merge of the pull request contains the appropriate ticket information. Currently there is no pre/post linting on the Dojo Toolkit repositories, so there is no need to utilise !strict in the commit message.