|
1 YUI 3: The Yahoo User Interface Library |
|
2 ======================================= |
|
3 |
|
4 [](http://travis-ci.org/yui/yui3) |
|
5 |
|
6 YUI is a free, open source JavaScript and CSS framework for building richly |
|
7 interactive web applications. YUI is provided under a BSD license and is |
|
8 available on GitHub for forking and contribution. |
|
9 |
|
10 Links |
|
11 ----- |
|
12 |
|
13 * [Home Page](http://yuilibrary.com/) |
|
14 * [Documentation](http://yuilibrary.com/yui/docs/) |
|
15 * [Blog](http://yuiblog.com) |
|
16 * [Latest Production Release](http://yuilibrary.com/download/yui3/) |
|
17 * [Forums](https://groups.google.com/forum/#!forum/yui-support) |
|
18 * [License](http://yuilibrary.com/license/) |
|
19 * [Contributor Info](https://github.com/yui/yui3/blob/master/CONTRIBUTING.md) |
|
20 * [Contributor Mailing List](https://groups.google.com/forum/?fromgroups#!forum/yui-contrib) |
|
21 * [Report a Bug](http://yuilibrary.com/yui/docs/tutorials/report-bugs/) |
|
22 * [Shifter, for building YUI](http://yui.github.com/shifter/) |
|
23 |
|
24 |
|
25 Source Info |
|
26 ----------- |
|
27 |
|
28 This is the active working source tree for YUI 3. It contains work in progress |
|
29 toward the next YUI 3 releases and may be unstable. |
|
30 |
|
31 We encourage you to use the latest source for evaluation purposes, testing new |
|
32 features and bug fixes, and to provide feedback on new functionality. Please |
|
33 refer to the "Latest Production Release" link above if you're looking for the |
|
34 latest stable release of YUI recommended for production use. |
|
35 |
|
36 If you plan on contributing to YUI, please join and monitor the "Contributor |
|
37 Mailing List" listed above. Information about milestones and tree closures |
|
38 will be made available there. |
|
39 |
|
40 |
|
41 ## Branch Information |
|
42 |
|
43 YUI's development happens on five main branches. The following describes what |
|
44 each of these code branches represents: |
|
45 |
|
46 * `live-docs`: Represents the latest GA release of YUI, plus any |
|
47 documentation-only updates. Any tweaks or additions to the docs for the |
|
48 latest release happen on this branch, and they are reflected on the website. |
|
49 |
|
50 * `master`: (Read-only) Contains everything in `live-docs`, plus code changes that will go |
|
51 into the next YUI release. The code changes in `master` are either bug fixes |
|
52 or small changes which should not break API compatibility. Patch releases |
|
53 will be cut from this branch; e.g. 3.6.x. *All code in this branch has fully |
|
54 passed all unit tests and should be stable.* |
|
55 |
|
56 * `3.x`: (Read-only) Represents the next major YUI release; e.g. 3.7.0. This is an |
|
57 integration branch which contains everything in `master`, plus larger code |
|
58 changes which will go into a future YUI release. The changes in `3.x` |
|
59 require a minor version increment before they are part of release, e.g., |
|
60 3.7.0. Preview Releases will be cut from this branch for developers to test |
|
61 and evaluate. *All code in this branch has fully passed all unit tests and should be stable.* |
|
62 |
|
63 * `dev-master` and `dev-3.x`: Current working branches containing code that |
|
64 **has not** been through the CI process. **Developers check their changes in to |
|
65 these integration branches for the automated testing system to validate.** Once they |
|
66 are validated, the code is merged into `master` and `3.x` respectively. **Never** check in to |
|
67 `master` or `3.x` directly. |
|
68 |
|
69 * `release-3.x.x`: Short-lived release branches where code checkins are carefully |
|
70 managed for extensive testing and release deployment. |
|
71 |
|
72 ## Source Tree |
|
73 |
|
74 The YUI source tree includes the following directories: |
|
75 |
|
76 * `build`: Built YUI source files. The built files are generated at |
|
77 development time from the contents of the `src` directory. The build step |
|
78 generates debug files (unminified and with full comments and logging), |
|
79 raw files (unminified, but without debug logging), and minified files |
|
80 (suitable for production deployment and use). |
|
81 |
|
82 * `src` Raw unbuilt source code (JavaScript, CSS, image assets, ActionScript |
|
83 files, etc.) for the library. Beginning with YUI 3.4.0, the `src` directory |
|
84 also contains all module-specific documentation, tests and examples. All |
|
85 modifications to the library and its documentation should take place in |
|
86 this directory. |
|
87 |
|
88 ## Initial Setup |
|
89 |
|
90 1. Fork the project on GitHub (http://www.github.com/yui/yui3). |
|
91 1. Clone the fork to your local environment for development. |
|
92 |
|
93 ## Do Good Stuff |
|
94 |
|
95 1. Create a feature branch to house atomic code changes. |
|
96 `git checkout -b myfeature upstream/master --no-track` |
|
97 1. Satisfy the contribution requirements |
|
98 (see [YUI Contribution Standards](https://github.com/yui/yui3/wiki/Contribution-Standards)). |
|
99 1. Push changes to your fork. |
|
100 1. Submit a pull request from your fork to the `live-docs`, |
|
101 `dev-master`, or `dev-3.x` branch for review. |
|
102 1. Incorporate community feedback. |
|
103 1. Push changes to your fork -- the pull request will automatically update. |
|
104 1. Rinse and repeat. |
|
105 |
|
106 All changes should continue to be made on the feature branch; that way the pull |
|
107 request you submit will automatically update to include them. Make sure to keep |
|
108 the feature branch updated with the latest changes from master, so that they |
|
109 don't diverge during your development process. |
|
110 |
|
111 ## Important Tips |
|
112 |
|
113 * Always work from a feature branch. Since all code submissions will be |
|
114 through a Pull Request, feature branches isolate changes from one submission to another. |
|
115 * Always start your new branch from the branch you want to submit to: |
|
116 `git checkout -b myfeature dev-master` |
|
117 * Remember to submit your Pull Request to the proper `dev-` branch and not |
|
118 `master` or `3.x`. |
|
119 |
|
120 ## Building |
|
121 |
|
122 To build YUI components install [Shifter](http://yui.github.com/shifter/) (`npm -g install shifter`) |
|
123 and then simply run `shifter` in that components directory. |
|
124 |
|
125 Shifter also allows you to rebuild the entire YUI src tree: |
|
126 |
|
127 cd yui3/src && shifter --walk |
|
128 |
|
129 |