From 8cc636dd448afb8df7147640a7fbfb67f7d53623 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sat, 10 Jan 2015 10:58:40 +0000 Subject: Docs: Clarify PHP Usage Clarify that PHP is not required for testing, add a link to the CONTRIBUTING page and tidy up. Closes gh-1418 --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++---------------------- README.md | 26 ++++++---------------- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d694c99c..8c1ceb034 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,68 +16,83 @@ This is the best way to contribute to jQuery UI. Please read through the full gu Every week (unless otherwise noted) the jQuery UI team has a meeting to discuss the progress of current work and to bring forward possible new blockers for discussion. The meeting is held on [IRC](http://irc.jquery.org) in the #jquery-meeting channel at [Noon EST](http://www.timeanddate.com/worldclock/fixedtime.html?month=1&day=17&year=2011&hour=12&min=0&sec=0&p1=43) on Wednesdays. Meeting notes are posted on http://meetings.jquery.org/category/ui/ after each meeting. -## Tips For Bug Patching +## Tips for Getting Started -### Environment: localhost w/ PHP, Node.js & Grunt +### Environment: Minimum Required -jQuery UI uses Node.js & Grunt to automate the building and validation of source code. +If you are contributing changes you will need a fork of jquery-ui (see [Getting the Source](#environment-getting-the-source)). If you just want the source code you could clone jquery-ui directly: -Some tests depend on PHP running locally, so make sure you have the following installed: - -* A web server with PHP support (any will do, such as [XAMPP](http://www.apachefriends.org/en/xampp.html) or [MAMP](http://www.mamp.info/en/index.html)) -* [Node.js](http://nodejs.org/) (includes NPM, necessary for the next step) -* Grunt (install with: `npm install -g grunt`) +```bash +git clone git://github.com/jquery/jquery-ui.git +cd jquery-ui +``` -### Build a Local Copy of jQuery UI +The tests can run in any local web server. Ideally you should test your patch in appropriate web browsers and if possible run `grunt` to lint the code and run automated tests (this will happen automatically when you create a pull request). See the [Recommended Setup](#environment-recommended-setup) for setting up Node.js so that the grunt command works. -Create a fork of the jQuery UI repo on GitHub at http://github.com/jquery/jquery-ui. +### Environment: Getting the Source -Change directory to your web root directory, whatever that might be: +* Create a fork of the jQuery UI repo on GitHub at http://github.com/jquery/jquery-ui. This will create a fork of jquery-ui in your Github account. +* You may want to clone jquery-ui under the path to your web server. If so, change to the required directory ```bash -$ cd /path/to/your/www/root/ +cd /path/to/your/www/root/ ``` -Clone your jQuery UI fork to work locally. - -*Note: be sure to replace `[USERNAME]` with your GitHub username.* +* Clone your jQuery UI git repo. ```bash -$ git clone git@github.com:[USERNAME]/jquery-ui.git +git clone git://github.com/[USERNAME]/jquery-ui.git +cd jquery-ui ``` -Change to the newly created directory. +*Note: be sure to replace `[USERNAME]` with your GitHub username.* + +* Add the official jQuery repository as a remote. We recommend naming it "upstream". ```bash -$ cd jquery-ui +git remote add upstream git://github.com/jquery/jquery-ui.git ``` -Add the official jQuery repository as a remote. We recommend naming it "upstream". +* Get in the habit of pulling in the "upstream" master to stay up to date as jQuery UI receives new commits. ```bash -$ git remote add upstream git://github.com/jquery/jquery-ui.git +git pull upstream master ``` -Get in the habit of pulling in the "upstream" master to stay up to date as jQuery UI receives new commits. +### Environment: Recommended Setup + +jQuery UI uses Node.js & Grunt to automate the building and validation of source code. Here is how to set that up: + +* Get [Node.js](http://nodejs.org/) (includes NPM, necessary for the next step) +* Install Grunt cli: ```bash -$ git pull upstream master +npm install -g grunt-cli ``` -Install the dependencies. +* Install local Node.js modules ```bash npm install ``` +The tests require a local web server and the samples contain some PHP, so a PHP web server may be useful. + +* Install a web server. Here are some you could use: + * Windows: [WAMP download](http://www.wampserver.com/en/) + * Mac: [MAMP download](http://www.mamp.info/en/index.html) + * Linux: [Setting up LAMP](https://www.linux.com/learn/tutorials/288158-easy-lamp-server-installation) + * [Mongoose (most platforms)](http://code.google.com/p/mongoose/) + * [http-server](https://www.npmjs.com/package/http-server) + +### Running the Tests + To lint the JavaScript, HTML, and CSS, as well as run a smoke test in PhantomJS, run grunt: ```bash -$ grunt +grunt ``` To run the tests for a specific plugin in your browser, open the appropriate file from the `/tests/unit/` directory, for example: `http://localhost/tests/unit/accordion/accordion.html`. The domain will be dependent on your local server configuration; if there is a port, be sure to include it. Ideally you would test in all of our [supported browsers](http://jqueryui.com/browser-support/), but if you don't have all of these browsers available, that's ok. - -Make sure to read our [commits and pull requests documentation](http://dev.contribute.jquery.org/commits-and-pull-requests/) for full details on working with branches and forks, as well as our commit guidelines. diff --git a/README.md b/README.md index edd49ab7b..998a3f24b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ If you are interested in helping develop jQuery UI, you are in the right place. To discuss development with team members and the community, visit the [Developing jQuery UI Forum](http://forum.jquery.com/developing-jquery-ui) or [#jqueryui-dev on irc.freenode.net](http://irc.jquery.org/). -## For contributors +## For Contributors If you want to help and provide a patch for a bugfix or new feature, please take a few minutes and look at [our Getting Involved guide](http://wiki.jqueryui.com/w/page/35263114/Getting-Involved). @@ -21,35 +21,21 @@ In general, fork the project, create a branch for a specific change and send a pull request for that branch. Don't mix unrelated changes. You can use the commit message as the description for the pull request. +For more information, see the [contributing page](CONTRIBUTING.md). ## Running the Unit Tests -Run the unit tests with a local server that supports PHP. No database is required. Pre-configured php local servers are available for Windows and Mac. Here are some options: - -- Windows: [WAMP download](http://www.wampserver.com/en/) -- Mac: [MAMP download](http://www.mamp.info/en/index.html) -- Linux: [Setting up LAMP](https://www.linux.com/learn/tutorials/288158-easy-lamp-server-installation) -- [Mongoose (most platforms)](http://code.google.com/p/mongoose/) +Run the unit tests manually with appropriate browsers and any local web server. See our [environment setup](CONTRIBUTING.md#environment-minimum-required) and [information on running tests](CONTRIBUTING.md#running-the-tests). +You can also run the unit tests inside phantomjs by [setting up your environment](CONTRIBUTING.md#user-content-environment-recommended-setup). ## Building jQuery UI -jQuery UI uses the [Grunt](http://github.com/gruntjs/grunt) build system. +jQuery UI uses the [Grunt](http://gruntjs.com/) build system. -To build jQuery UI, you must have [node.js](http://nodejs.org/) installed and then run the following commands: +To build jQuery UI, [setup your environment]([setting up your environment](CONTRIBUTING.md#environment-minimum-required)) and then run the following commands: ```sh - -# Install the Grunt CLI -npm install -g grunt-cli - -# Clone the jQuery UI git repo -git clone git://github.com/jquery/jquery-ui.git -cd jquery-ui - -# Install the node module dependencies -npm install - # Run the concat task to concatenate files grunt concat -- cgit v1.2.3