Developer Workflow
(This information supplements the information at http://yuilibrary.com/yui/docs/tutorials/contribute/).
If you are new to contributing to YUI, Contribute.md is a good place to start.
This document explains YUI's branching strategy and developer workflow for making and submitting contributions to the project.
This document assumes you already have Git installed and working. If you don't, see Tutorial: Set Up Your Git Environment for more info. (GitHub also has some great guides if you are new to Git.)
Also be sure to sign our CLA, if you haven't already, before you contribute to YUI.
YUI's development happens on five main branches. The following describes what each of these code branches represents:
-
live-docs: Represents the latest GA release of YUI, plus any documentation-only updates. Any tweaks or additions to the docs for the latest release happen on this branch, and they are reflected on the website. -
master: (Read-only) Contains everything inlive-docs, plus code changes that will go into the next YUI release. The code changes inmasterare either bug fixes or small changes which should not break API compatibility. Patch releases will be cut from this branch; e.g. 3.6.x. All code in this branch has fully passed all unit tests and should be stable. -
3.x: (Read-only) Represents the next major YUI release; e.g. 3.7.0. This is an integration branch which contains everything inmaster, plus larger code changes which will go into a future YUI release. The changes in3.xrequire a minor version increment before they are part of release, e.g., 3.7.0. Preview Releases will be cut from this branch for developers to test and evaluate. All code in this branch has fully passed all unit tests and should be stable. -
dev-masteranddev-3.x: Current working branches containing code that has not been through the CI process. Developers check their changes in to these integration branches for the automated testing system to validate. Once they are validated, the code is merged intomasterand3.xrespectively. Never check in tomasteror3.xdirectly. -
release-3.x.x: Short-lived release branches where code checkins are carefully managed for extensive testing and release deployment.
If this is your first time making a change to YUI, you'll need to set up your coding environment to be able to build YUI and work with git.
Many Mac OS X and Linux systems already have git installed. If your system doesn't, see How to Set Up Your Git Environment for instructions.
Download and install Node.js if you don't already have it installed. All of YUI's build tools rely on Node.js.
Yogi is YUI's command line helper tool, which you'll use to build and test YUI changes. (You may also need to install phantomjs.)
To install Yogi using npm (which comes with Node.js), run:
$ npm -g install yogiIf you don't yet have a GitHub account, get one! You'll need it to send a pull request to YUI.
Go to YUI's GitHub page and click the "Fork" button to create your own personal GitHub fork of YUI. Follow GitHub's instructions to clone the fork to your local machine, then add an upstream remote to your local repo that points to YUI's official repo:
$ git remote add upstream git://github.com/yui/yui3.gitIf this is your first time contributing to YUI, you'll need to digitally sign the YUI CLA so that we can accept your contributions.
Before starting work on a change, make sure you have the latest YUI source. Your YUI fork should:
- Always be up-to-date with dev-master
- Always be pushed to daily (get upstream changes and push to your fork).
- Always be in sync with your current work.
First, decide what YUI branch you want to base your change on (see the branching strategy section above). Then cd to your local YUI clone and run the following commands.
Note: these examples assume you'll base your change on the dev-3.x branch, but you can replace dev-3.x in every example that follows with whichever development branch makes the most sense for your change.
$ git checkout dev-3.x
$ git pull upstream dev-3.xIt's best to develop changes in a "topic branch", which is a branch that only contains commits related to a single change. This will make merging easy later and keep your pull request nice and clean. Use dev-master or dev-3.x as your base branch, depending on the scope of your change.
Think of a short but descriptive name for your topic branch, then create it like this (replace my-topic-branch with the name you prefer):
$ git checkout -b my-topic-branch dev-3.xMake any code, test, or documentation changes you want to make.
Keep your code changes relevant (that is, don't go around reformatting files or refactoring code that's unrelated to your change), and try to adhere to the existing coding style of any files you change.
Be sure to write unit tests for any bugs you fix or new functionality you add! We won't accept pull requests that don't include tests.
See Contribution Standards for details on YUI's code quality standards and testing guidelines.
Run yogi build from a module directory to build that module. Run yogi test from a module directory to run that module's unit tests. Please note yogi test uses PhantomJS to test your code. If you wish to test your code within a browser, run yeti <name>.html, where name is the name of the HTML file which contains your tests. Please make sure your code tests successfully in all of the environments located here before submitting your pull request.
Please note when adding, or removing modules from the src directory, you must regenerate the meta data for the YUI seed file. You can do this by running the yogi loader command from the src directory, which will regenerate the meta data and rebuild the seed file.
In the source directory of every YUI module there's a file named HISTORY.md. This file contains a Markdown-formatted history of all the changes that have been made to that module.
If you made changes to one or more modules, please update those modules' HISTORY.md files and describe the changes you made. This step is optional, but it'll make the reviewer's job easier and we'll love you for it.
If this is the first entry for this new version, and it's not already there, include an entry like this:
@VERSION@
------
* [your info here]
This token will be replaced by the correct version at release time.
After you've tested your change and ensured that it works in all major browsers, commit it to git.
Note: Please commit source files and documentation only. Don't commit anything in the build/ directory.
$ git add <one or more changed source files>
$ git commit -m "Description of the change"Be sure to merge in the latest upstream changes frequently, and especially before you submit a pull request.
$ git pull upstream dev-3.xThis may generate a merge commit. That's fine. If there are conflicts, you may need to resolve them in order to finish the merge. If you're not sure how to resolve conflicts, feel free to ask on the #yui IRC channel on Freenode or the yui-contrib mailing list.
When you're ready to share your changes with the world, push your topic branch to your GitHub fork of YUI. This will only modify your fork; it won't modify the official YUI repo.
$ git push origin my-topic-branchAfter you've finished your change and pushed your topic branch to GitHub, browse to your topic branch on GitHub and click the Pull Request button.
Be sure to set the base branch dropdown to the correct YUI development branch (live-docs, dev-master, or dev-3.x).
Give your pull request a descriptive title and a detailed description of the changes you made. If you added new features, describe what those features are, how they work, and why you think they're useful.
The more descriptive your pull request is, the more likely it will be reviewed quickly and accepted.
If this is ongoing work you should prefix the title of the pull request with "[WIP] some new feature" and push to that branch often. This keeps a record of your progress. If you want feedback from another member of the YUI community, simply use the @username syntax in a comment and ask them to take a look.
YUI core commiters, reviewers, and other YUI users will review your pull request and may leave suggestions or other feedback, or they may ask questions about your changes. GitHub will email you a notification whenever someone comments on your pull request.
Please take feedback and criticism in a constructive spirit and answer any questions.
If a reviewer requests changes, you can make these changes in your local topic branch, commit them, and push them to your GitHub repo as described above. GitHub will automatically update the pull request with your new commits as long as you keep them in the same topic branch.
Not all pull requests will be approved. A YUI reviewer may decide that the change isn't necessary, or that a different approach would be better, or that it's just not something that should become part of YUI.
If your pull request isn't approved, don't feel bad! Your contributions are still very welcome, and we encourage you to send us more pull requests.
- Clone YUI.
git clone -b <branch_name> https://github.com/yui/yui3.git- Navigate to the cloned yui3 directory.
cd yui3- Install the modules YUI requires:
npm i- Make sure you have grunt-cli installed globally.
npm i -g grunt-cli- Install grunt locally.
npm i grunt- Run the release task.
grunt releaseAfter all of this is said and done, there should be a newly created release directory. This directory contains the few kinds of builds in which YUI deploys.
The build inside of the cdn directory is the version of YUI which you'll find on Yahoo's CDN.
- Setup Combo Loader
npm install -g combohandler
NODE_ENV=production combohandler --port 8000 --root /yui3:/path/to/yui3/release/version/cdnAnd in your app
<script src="http://example.com:8000/yui3?build/yui/yui-min.js"></script>
<script>
YUI({
comboBase: 'http://example.com:8000/yui3?',
combine : true,
root : 'build/'
}).use('node', function (Y) {
// YUI will now automatically load modules from the custom combo handler.
});
</script>-
Set up your environment as described above. You should have
yogiinstalled and have a local clone of YUI on your development machine. -
Go to the directory you want to build within YUI and just run
$ yogi build. (yogiusesshifterunder the hood.)- For example
$ cd yui3/src/anim & yogi build - Output goes to
../../build
- For example
- For help with
yogijust runyogi --help - Make sure you are always running the latest version of
yogi -
yogi buildjust builds the tree.grunt buildrunsyogi buildandnpm i.
The information in this section is for YUI core reviewers and commiters only. If you're not a reviewer or committer, this doesn't apply to you.
Note: While all PRs require the approval of a reviewer, committers should merge their own PRs once a reviewer has signed off. Committers, please don't expect reviewers to merge your changes for you.
Read the diffs associated with the pull request. Do the proposed changes make sense? Do they fix a problem or improve YUI in a valuable way? Are they maintainable? Does the code adhere to the style and standards of the changed files and the library in general? Do they include unit tests? If they do not include unit tests, it will be your responsibility to write them.
Comment on code that you have questions about or that you think should be changed. Ask questions about the changes if anything needs clarification.
If the code changes look good and you're inclined to accept the pull request, the next step is to run unit tests and make sure they all pass. If there are any downstream dependencies, verify that their unit tests continue to pass as well.
Follow GitHub's instructions for merging the pull request into your local repo via the command line, but don't push the changes upstream yet.
After merging the changes into your local repo, build any modules whose source files changed, then run the unit tests for those modules in all major browsers. If there are failures, paste the failure info into a comment on the pull request.
Consider asking another YUI community member to review the code as a sanity check.
If the contributor didn't update the HISTORY.md files for changed modules, update them now.
If the contributor didn't include documentation and for some reason you didn't reject the pull request, then it's your job to write those docs before merging the changes.
Commit all the build files and other local changes (HISTORY.md, docs, etc.) you've made.
Merge the topic branch into the appropriate development branch (live-docs, dev-master, or dev-3.x).
$ git checkout dev-3.x
$ git merge my-topic-branchIf there are any conflicts, resolve them. Then push the changes upstream to automatically close the PR.
$ git push upstream dev-3.xImmediately verify that the automated build passes all unit tests and no breakage has occurred as a result of checking the code in.
- Find the most recent common commit between your dev branch (i.e.
dev-3.x) and a release branch (i.e.release-3.12.0).
To discover this common commit, use something like:
$ git merge-base dev-3.x release-3.12.0
-
Create a new branch from that commit.
-
Cherry-pick your changes into that new branch (from your own development branch say
bugfix-1234). -
Issue a pull request against the release branch and state which other
dev-*branch it should be merged into. -
Reviewers only: Merge that branch into both the dev branch (i.e.
dev-3.x) and release branch (i.e.release-3.12.0).
-
shifter - Build YUI and Gallery -
sudo npm -g i shifter -
yogi - ( YUI or Gallery Interface ) Command Line Helper for YUI -
sudo npm -g i yogi -
Grover - YUITest wrapper for PhantomJS -
sudo npm -g i grover(Make sure you have phantomjs installed) - Yeti - Automates tests written with QUnit, Jasmine, Mocha with Expect.js assertions, Dojo Objective Harness, or YUI Test.
- UglifyJS - Used to compress js
- Istanbul - Code coverage tool
- GearJS - Build System for Node.js and the Browser