Contributing to YUI 3 Gallery

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 Gallery codeline.

Forking the Project

Your first step in creating a fork of the code is to visit the YUI 3 Gallery project page on GitHub: http://github.com/yui/yui3-gallery/. 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-gallery.git

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

Initialized empty Git repository in /src/dev/contrib/yui3-gallery/.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-gallery; git remote add upstream git://github.com/yui/yui3-gallery.git

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

pu = !"git fetch origin -v; git fetch upstream -v; 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-gallery
 = [up to date]      master     -> origin/master
From git://github.com/yui/yui3-gallery
 * [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-gallery
 = [up to date]      master     -> origin/master
From git://github.com/yui/yui3-gallery
 = [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-gallery
 = [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-gallery
   3dccf5b..99efb0c  master     -> upstream/master
 * [new tag]         yui3-gallery-644   -> yui3-gallery-644
From git://github.com/yui/yui3-gallery
 * [new tag]         yui3-gallery-643   -> yui3-gallery-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 lasted 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 CDN 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 lasted 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."

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 CDN Request.

Submitting a CDN Request

CDN 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 CDN Requests must be issued from YUILibrary.com; the YUI Team is no longer accepting CDN Requests from GitHub.

To begin the CDN Request process, visit the My Modules page, click on the module you would like to submit the CDN request for, then click the Submit CDN Request link.

This will bring up a CDN 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 CDN Request button.

This will open a details window to allow you to add a short message to the request.

At this point your module will be in the CDN Request Queue. The YUI Team will evaluate the submitted code to determine if it can be pushed to the CDN.

You will receive an email from the system confirming each step as it is completed to update you on the status of your module in the review process; including a email notification when your module has been included in a CDN push.

Checking out a CDN Request

Occasionally developers want to check out a CDN 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-gallery
git remote add gh-davglass git://github.com/davglass/yui3-gallery.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 CDN 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"