Skip to content
This repository has been archived by the owner on Oct 30, 2018. It is now read-only.

Contributing Code to Mojito

Jump to bottom
Joe Catera edited this page Sep 24, 2013 · 7 revisions

About This Tutorial

This tutorial will help you to make code and documentation contributions to Mojito.

In particular, this tutorial explains how to set up your Mojito development environment, how to test your proposed submissions, make individual pull requests, and maximize the likelihood of having your contributions integrated with the main Mojito repository.

Please be sure to sign our CLA before you submit pull requests or otherwise contribute to Mojito. This protects Mojito developers, who rely on Mojito's BSD license.

Initial Setup

Install Git

Mojito development is managed via Git and GitHub. If you don't have Git installed yet, follow the instructions in the YUI tutorial Set Up Your Git Environment to install Git and get set up with both YUI and Mojito (which leverages YUI).

Get a GitHub Account

You will need a GitHub account to contribute to Mojito. If you don't have a GitHub account don't worry, they're free :). Just go to Sign up for GitHub to create a new account.

Fork Mojito

All initial work on Mojito is done in a "fork" or clone of the main Mojito repository's develop branch. You only need to fork the main repository once; from that point forward, you can work within unique branches of your fork.

To create your initial fork of Mojito, log in to GitHub and visit the Mojito project page on GitHub: http://github.com/yahoo/mojito/.

Mojito development is managed on the develop branch of the repository, so you'll next want to select develop from the branch menu, roughly one-third down the page on the left side.

Now you need to create your fork of yahoo/mojito/develop by clicking Fork in the upper right of the repository home page. When the forking process completes, you will be presented with information about your new repository.

Clone Your Mojito Fork Locally

Once you have a fork on GitHub, you need to create a local clone on your development machine. This is where you'll do your actual editing and development work, pushing commits to your fork at appropriate times.

Clone your newly created fork by running git clone [url], where url is "Your Clone URL" (and not the "Public Clone URL"). Cloning copies your fork onto your local machine. For example, if your user name on GitHub were 'mojit0', you'd enter::

$ git clone git@github.com:mojit0/mojito.git --branch develop

The output from the above command will look something like the following::

Initialized empty Git repository in /src/dev/contrib/mojito/.git/
remote: Counting objects: 31520, done.
remote: Compressing objects: 100% (8945/8945), done.
remote: Total 31520 (delta 21295), reused 30725 (delta 20682)
Receiving objects: 100% (31520/31520), 12.57 MiB | 1814 KiB/s, done.
Resolving deltas: 100% (21295/21295), done.

Add the Upstream Repository

As you develop, you'll need to stay in sync with the main yahoo/mojito develop branch. To do this, you'll need a remote repository reference that points back to the original yahoo/mojito repository.

This step needs to be done from inside the project you just cloned::

$ cd mojito
$ git remote add upstream git://github.com/yahoo/mojito.git

Branch-Based Workflow

Each time you start working on a set of related changes to Mojito, you should create a topic branch. Isolating your changes to a topic branch makes it easy to resolve conflicts with the upstream repository and to manage comments and changes recommended by reviewers to your code.

Update Your Develop Branch

Before starting work on a new feature, or any other time you feel the need to sync your fork's develop branch with the main repository, run the following from your local repo's develop branch:

$ git pull upstream develop

or alternatively:

$ git remote update
$ git rebase upstream/develop

Create A Topic Branch

You can create a new topic branch directly off your develop branch if it's synced (replace mybranch with a meaningful branch name):

$ git checkout -b mybranch develop

or, create a new topic branch directly off of upstream/develop (replace mybranch with a meaningful branch name) by running::

$ git fetch upstream
$ git checkout -b mybranch upstream/develop --no-track

Edit, Delint (Fix), Test, Document, Repeat

With your topic branch in place you can now edit files, add features, and/or fix bugs. Go crazy!

It's a good practice to start by creating unit tests which define success for your work, then proceed with development until those tests pass (i.e., test-driven development (TDD)). Your contribution will not be accepted without proper unit tests. Mojito can help you with this process with its built-in tests. Just follow the steps below.

  1. Change to the mojito directory and confirm you are on the develop branch.

  2. Install the dependencies needed to run tests:

     $ npm install

  3. Create your tests, place them in the proper Mojito test location(s).

  4. Run Mojito's unit and functional tests:

     $ npm test

  5. Before you commit your changes, it's also helpful to test for JavaScript lint:

     $ npm lint

To run tests on the client, see Running Tests with Selenium. See also Mojito Framework's Unit and Functional Tests for information about setting up your environment, testing options, and test results.

As you complete each small unit of work and your code is lint-free and passing unit tests, you should commit it.

Please document your code as you go. Great commenting and API documentation will help others review your code and get your contribution merged. If your contribution may require changes to our user guide documentation, please note that in your pull request, and we can work with you on getting those done too.

Commit Early, Commit Often

Whenever you're at a good stopping point, as frequently as possible, commit your changes to your topic branch:

$ git commit -am "Give a good description here, better than this one."

Reference Issue Numbers in Commit Messages

Mojito issues are managed on GitHub in the GitHub issues list. We strongly encourage you to enter the related issue number(s) for any work you do.

The following syntax is supported:

$ git commit -m "[fix #1234] ...description..."
$ git commit -m "[fixes #1234] ...description..."
$ git commit -m "[fixed #1234] ...description..."
$ git commit -m "[close #1234] ...description..."
$ git commit -m "[closes #1234] ...description..."
$ git commit -m "[closed #1234] ...description..."

Resync, Retest, and Push

It's a good idea to regularly pull upstream changes into your branch and test against this latest code from the main Mojito project repository::

$ git pull upstream develop
$ npm test

If your code is complete, lint-free, and passes all your new unit tests (you wrote some right? ;)), it's time to push your topic branch to GitHub in preparation for submitting a pull request:

$ git push origin mybranch

Submit a Pull Request

Pull requests notify the Mojito Team that you want us to review your code and start the process of getting it merged into the official release. We accept pull requests via GitHub's Fork + Pull Model.

Contributing to Documentation

Mojito documentation is located in the /docs directory. To generate HTML documentation, run the following commands from the documentation directories. You will need Sphinx to generate the documentation.

$ cd docs/dev_guide
$ make html

After you make changes to the documentation (docs/dev_guide), re-generate the HTML documentation to make sure that the reStructuredText used to author the documentation is correct and then make a pull request just as you would for code contributions.

Clone this wiki locally