Contributing to YUI

Laying the Groundwork

To get started contributing to YUI, you need to create a couple of accounts and fill out some paperwork.

• Create a YUILibrary.com account. This account will be needed in later steps.
• Create a free account on GitHub. This account is needed to gain full access to the source code.
• Sign and submit a Contributor License Agreement (CLA).

  Please include your YUILibrary.com username, your GitHub username and the email address you used for both accounts. CLAs must be printed out, signed and mailed in to take effect; we cannot accept CLAs electronically at this time.

Getting the Source Code

This section assumes you already have Git installed and working. If you haven't, visit our Git FAQ for more info.

Now you have to get the source code. In this example you will be working with the YUI 3 codeline.

Forking the Project

Your first step in creating a fork of the code is to visit the YUI 3 project page on GitHub: http://github.com/yui/yui3/. Be sure you are logged in on GitHub as you begin to follow these steps.

Now you need to create your fork. To do this, you simply click the button. When the fork has completed, you will be presented with information about your new repository.

Note: These examples were created while logged in as the yui-contrib user, you should substitute yui-contrib with your GitHub username.

Cloning your Project

Now you need to clone the newly created fork. Cloning makes a copy of your fork on another machine. Make sure you use the "Your Clone URL" and not the "Public Clone URL".

git clone git@github.com:yui-contrib/yui3.git

The output of the above command will look something like this:

Initialized empty Git repository in /src/dev/contrib/yui3/.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.

Adding an Upstream Project

Now you need to add a remote project to this one. This will always be the "Public Clone URL" of the official YUI project you are working on. Executing the following command establishes the relationship between your local git repository and the upstream YUI fork from which it was cloned.

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

cd yui3; git remote add upstream git://github.com/yui/yui3.git

Add this line to your ~/.gitconfig under [alias]

For OSX/Linux

pu = !"git fetch origin -v; git fetch upstream -v; git merge upstream/master"

For Windows

pu = !"git fetch origin -vn git fetch upstream -vn git merge upstream/master"

That will allow you to execute git pu to pull your repo, then pull the main YUI repo, then merge the YUI changes in.

The first time it's run, the output will look something like this:

From git://github.com/yui-contrib/yui3
 = [up to date]      master     -> origin/master
From git://github.com/yui/yui3
 * [new branch]      master     -> upstream/master
Already up-to-date.

This creates the upstream/master branch on your local project. It's used to track upstream changes.

If there are no upstream updates, it will look something like this:

From git://github.com/yui-contrib/yui3
 = [up to date]      master     -> origin/master
From git://github.com/yui/yui3
 = [up to date]      master     -> upstream/master
Already up-to-date.

If there are upstream updates, it will look something like this:

From git://github.com/yui-contrib/yui3
 = [up to date]      master     -> origin/master
remote: Counting objects: 61, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 36 (delta 25), reused 0 (delta 0)
Unpacking objects: 100% (36/36), done.
From git://github.com/yui/yui3
   3dccf5b..99efb0c  master     -> upstream/master
 * [new tag]         yui3-644   -> yui3-644
From git://github.com/yui/yui3
 * [new tag]         yui3-643   -> yui3-643
Merge made by recursive.
 api/event-target.js.html                 |   12 ++++++------
 build/event-custom/event-custom-debug.js |   10 +++++-----
 build/event-custom/event-custom-min.js   |    4 ++--
 build/event-custom/event-custom.js       |   10 +++++-----
 build/yui-base/yui-base-debug.js         |   19 ++++++++++++++-----
 build/yui-base/yui-base-min.js           |    4 ++--
 build/yui-base/yui-base.js               |   19 ++++++++++++++-----
 build/yui/yui-debug.js                   |   19 ++++++++++++++-----
 build/yui/yui-min.js                     |    4 ++--
 build/yui/yui.js                         |   19 ++++++++++++++-----
 src/event-custom/js/event-target.js      |   10 +++++-----
 src/yui/js/yui-array.js                  |   19 ++++++++++++++-----
 12 files changed, 97 insertions(+), 52 deletions(-)

You should issue this command often, to make sure you are up to date with the latest YUI code.

Simple (non-branch) Workflow

This is a simple (non-branch) workflow that should work for most contributors.

Update to the latest code.

git pu

Edit some files, add some features, fix some bugs.

git commit -am "Give a good description here."

Edit some files, add some features, fix some bugs.

git commit -am "Give a good description here."

Push the changes back up to GitHub. A push can be done at any time after one or more Commits have been made.

git push origin master

Submit a Pull Request.

Branch-Based Workflow

This workflow is slightly more complicated and should be used by developers that are used to this flow.

Update to the latest code.

git pu

Create a local branch called myfeature on which to work.

git checkout -b myfeature

Edit some files, add some features, fix some bugs.

git commit -am "Give a good description here."

Update to the latest code.

git fetch upstream

Merge the changes into your branch.

git merge upstream/master

Switch back to the master branch.

git checkout master

Merge in your changes.

git merge myfeature

Push the changes back up to GitHub. Note: this can be done at any time.

git push origin master

Submit a Pull Request.

Submitting a Pull Request

Pull Requests notify the YUI Team that you want us to pull your code and start the process of getting it merged into the official release.

All Pull Requests must be issued from YUILibrary.com; the YUI Team is no longer accepting Pull Requests from GitHub.

To begin the Pull Request process, visit the project page for the project that you forked and click the Pull Request link at the top of the page.

This will bring up a Pull Request Query page. This page will use the GitHub username bound to your YUILibrary.com account to query GitHub and gather information from your project fork.

This page will auto-query GitHub and try to gather as much information as it can about your fork of the project.

If you are using a branch to develop on, you can customize the query by changing the branch and clicking Query.

After clicking Query, you will see a list of the latest commits from your GitHub fork.

Select the commit that you want to submit and click the Submit Pull Request button.

This will open a details window to allow you to pick a component that you want to bind the Pull Request to as well as allow you to add a short message to the request.

Note: The message is a required field; we must know what problem you're solving or what functionality you're adding before we evaluate your code.

Once this step is completed a ticket will be created in the system with the information provided by this Pull Request.

At that point, it's a normal ticket and can be followed and tracked as usual. The owner of the component will comment and act on the ticket shortly after receiving it.

Checking out a Pull Request

Occasionally developers want to check out a Pull Request issued by another user. You can do this will the following commands.

If this is your first time pulling this user's project, then you have to do some setup work.

In these examples, you will be working with a submission from the GitHub user: davglass

cd yui3
git remote add gh-davglass git://github.com/davglass/yui3.git

Now you need to create/switch to a working branch:

//Not created one yet
git co -b gh-davglass

//Switch to already created branch
git co gh-davglass

If you receive this error "fatal: git checkout: branch gh-davglass already exists", use the second option.

Pull in the code from davglass's master branch.

git pull gh-davglass master

If davglass is working on a different branch (test):

git pull gh-davglass test

Next, reset the branch to the commit that was submitted in the Pull Request (dcdf332ac).

git reset dcdf332ac

Running git log will show that we are now located at this commit:

commit dcdf332ac871e588177e21c7cbd0045657826f84
Author: Adam Moore 
Date:   Tue Oct 6 08:28:38 2009 -0700

Added global config support (YUI_config).  Fixed detach by signature w/o Node [fixes bz3090033].

From here, you can run unit tests and check the code to make sure the fix does what you want it to do and behaves accordingly.

To get back to HEAD:

git reset --hard HEAD

Now you may pull the commit in from the other branch:

git co master
git merge dcdf332ac

git commit -m "fix #1234"
git commit -m "fixes #1234"
git commit -m "fixed #1234"
git commit -m "close #1234"
git commit -m "closes #1234"
git commit -m "closed #1234"

git commit -m "ref #1234"
git commit -m "refs #1234"
git commit -m "dealswith #1234"