Permalink
Browse files

added page listing for testers, removed old readme content, expanded …

…css section, added test section
  • Loading branch information...
1 parent 1567656 commit 2719b1816e59b199e90e680fa47e787407bdd5f9 @johnbender johnbender committed Jun 12, 2012
Showing with 70 additions and 139 deletions.
  1. +38 −124 README.md
  2. +31 −14 build/tasks/config.js
  3. +1 −1 grunt.js
View
162 README.md
@@ -16,6 +16,7 @@ When [submitting issues on github](https://github.com/jquery/jquery-mobile/issue
4. Expected outcome
5. Actual outcome
6. Browers tested
+7. Library version
Also, in the interest of creating more readable issues please include code snippets inside a triple backtick box appropriate for the JavaScript/HTML/CSS snippet you wish to discuss. More information is available at the [introduction page](http://github.github.com/github-flavored-markdown/) for github flavored markdown (see, Syntax Highlighting).
@@ -27,24 +28,22 @@ When submitting a pull request for review there are few important steps you can
2. Follow the [jQuery Core style guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
3. Limit the scope to one Issue/Feature
4. Small focused commits, ideally less than 10 to 20 lines
-5. Avoid merge commits (see Pro Git's chapter on [Rebasing](http://git-scm.com/book/ch3-6.html))
+5. Avoid merge commits (see Pro Git's chapter on [Rebasing](http://git-scm.com/book/ch3-6.html), [Development](#development))
Taken together, the above reduces the effort that's required of the contributor reviewing your pull request.
## Build/Customization
Currently the library is shipped on the jQuery CDN/download as a single monolithic JavaScript file that depends on jQuery Core (not included) and a similarly bundled CSS file. For users we support the following build targets:
-1. `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
-2. `css` - resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
-3. `docs` - build the js and css, and make the docs ready for static consumption
-4. `zip` - package the documentation in zip format for distribution
+* `js` - resolve dependencies, build, concat, and minify the JavaScript used for jQuery Mobile
+* `css` - resolve dependencies, build, concat, and minify all the css, just the structure css, and just the theme css
+* `docs` - build the js and css, and make the docs ready for static consumption
+* `zip` - package the documentation in zip format for distribution
### Requirements
-The build requires [node.js](http://nodejs.org/) and its packaged npm package manager. For other build targets like `docs` and `zip` it also requires at least a Bash shell with the addition of Make providing a layer of user friendliness if necessary.
-
-For more information on installing node please see its [documentation](http://nodejs.org/#download). For Bash and Make please refer to the appropriate documentation for your opperating system.
+The build requires [node.js](http://nodejs.org/) and its packaged npm package manager. For other build targets like `docs` and `zip` it also requires Bash. For more information on installing node please see its [documentation](http://nodejs.org/#download). For Bash and Make please refer to the appropriate documentation for your opperating system.
### Commands
@@ -59,10 +58,6 @@ If you want to use the `docs` and `zip` targets you will need bash and they can
grunt docs # or `grunt zip`
-Alternatively if you have `make` installed on your system
-
- make docs # or `make zip`
-
### JavaScript
As of version 1.1 the library uses dependency management in the JavaScript build by providing [AMD modules](https://github.com/amdjs/amdjs-api/wiki/AMD) which can be added or removed from the core mobile meta module `js/jquery.mobile.js`.
@@ -89,149 +84,68 @@ index 6200fe6..3a4625c 100644
'./jquery.mobile.links',
```
-And then run the build (for platform variations see [Posix](#posix) or [Windows](#windows))
+And then run the build:
grunt js
### CSS
-To build using a custom theme simply specify the name with an environment variable.
-
- THEME=valencia grunt css
+To create a new theme:
-This assumes the theme css files are available in the `css/theme/$THEME/` directory relative to the project root.
+1. Copy the `default` folder from CSS/Themes to a new folder named after your new theme (eg, `my-theme`).
+2. Add customizations to the `jquery.mobile.theme.css` file.
+3. From the project root run the following `grunt` command:
-### Posix
+ THEME=my-theme grunt css
-### Windows
+4. The output will be available in the `$PROJECT_ROOT/compiled`
-The additonal dependency on node.js in the interest of providing users on non posix platforms with the ability to compile at least the CSS and JavaScript.
+Again assumes the theme css files are available in the `css/theme/$THEME/` directory relative to the project root.
## Development
-### Server
-
-### Testing
-
-
-
-=======================
-[Official Site: http://jquerymobile.com](http://jquerymobile.com)
-
-[Demos and Documentation](http://jquerymobile.com/test/)
-
-How to build your own jQuery Mobile CSS and JS files
-====================================================
-Clone this repo and build the js and css files (you'll need Git and Make installed):
-
- git clone git://github.com/jquery/jquery-mobile.git
- cd jquery-mobile
- make
-
-A full version and a minified version of the jQuery Mobile JavaScript and CSS files will be created
-in a folder named "compiled". There is also now a Structure only css file so you can add your own theme on top of it.
-
-Alternatively if you have node.js installed you can run
-
- npm install
- node node_modules/.bin/grunt <js|css>
-
-to build either the js or css. This is usefull especially if you're on Windows without support for the make tool and bash.
-
-How to build a self-contained version of the Docs/Demos
-=======================================================
-Once you have your own cloned repo on your computer:
-
- make docs
-
-The docs will be built and available in the compiled/demos folder. You can move this folder to your web server or
-other location. It has no dependencies on anything other than a basic HTML web server.
-
-
-
-Submitting bugs
-===============
-If you think you've found a bug, please report it by following these instructions:
-
-1. Visit the [Issue tracker: https://github.com/jquery/jquery-mobile/issues](https://github.com/jquery/jquery-mobile/issues)
-2. Create an issue explaining the problem and expected result
- - Be sure to include any relevant information for reproducing the issue
- - Include information such as:
- * Browser/device (with version #)
- * The version of the jQuery Mobile code you're running
- * If you are running from a git version, include the date and/or hash number
- - Make sure that the bug still exists at http://jquerymobile.com/test/ as it may be fixed already
- - You can use the CDN hosted JS and CSS files to test in your own code by using:
- * [JS](http://code.jquery.com/mobile/latest/jquery.mobile.min.js)
- * [CSS](http://code.jquery.com/mobile/latest/jquery.mobile.min.css)
- - Include a link to some code of the bug in action. You can use either of these services to host your code
- * [jsbin](http://jsbin.com)
- * [jsfiddle](http://jsfiddle.net)
-3. Submit the issue.
-
-Recommended: [JS Bin issue template with instructions](http://jsbin.com/awoluv/edit)
+The root of the repository is also the root of the documentation and, along with the test suite, acts as the test bed for bug fixes and features. You'll need to set up a server and get the test suite running before you can contribute patches.
-Issues concerning the jQuery Mobile Theme Roller can be submitted at the [Theme Roller repo: https://github.com/jquery/web-jquery-mobile-theme-roller](https://github.com/jquery/web-jquery-mobile-theme-roller)
+### Server
-Submitting patches
-==================
-To contribute code and bug fixes to jQuery Mobile: fork this project on Github, make changes to the code in your fork,
-and then send a "pull request" to notify the team of updates that are ready to be reviewed for inclusion.
+Most of the documentation and testing pages rely on PHP 5+, and as a result Apache and PHP are required for development. You can installthem using one of the following methods:
-Detailed instructions can be found at [jQuery Mobile Patching](https://gist.github.com/1294035)
+* one-click - [MAMP](http://www.mamp.info/en/downloads/index.html) for OSX, [XAMP](http://www.apachefriends.org/en/xampp.html) for OSX/Windows
+* existing webserver - eg, `~/Sites` directory on OSX.
+* virtual machine - If [Vagrant](http://vagrantup.com) is installed you can add [this remote/branch](https://github.com/johnbender/jquery-mobile/tree/vagrant) and `vagrant up`
-Running the jQuery Mobile demos & docs locally
-==============================================
-To preview locally, you'll need to clone a local copy of this repository and point your Apache & PHP webserver at its
-root directory (a webserver is required, as PHP and .htaccess are used for combining development files).
+In addition to vanilla Apache the folloing modules are requied:
-If you don't currently have a webserver running locally, there are a few options.
+* Rewrite (mod\_rewrite.so)
+* Expire (mod\_expires.so)
+* Header (mod\_headers.so)
-If you're on a Mac, you can try dropping jQuery Mobile into your sites folder and turning on Web Sharing via System
-Prefs. From there, you'll find a URL where you can browse folders in your sites directory from a browser.
+Once you have your webserver setup you can point it at the project directory.
-Another quick way to get up and running is to download and install MAMP for Mac OSX. Once installed, just open MAMP,
-click preferences, go to the Apache tab, and select your local jQuery Mobile folder as the root. Then you can open a
-browser to http://localhost:8888 to preview the code.
+### Testing
-Another alternative is XAMPP (Mac, Windows). You need to actually modify Apache's httpd.conf to point to your checkout:
-[Instructions](http://www.apachefriends.org/en/xampp.html)
+Automated testing forms the backbone of the jQuery Mobile project's QA activities. As a contributor or patch submitter you will be excpected to run the test suite in for the area which you patches affect. Our continuous integration server will address the rest.
-You need the following Apache modules loaded:
+There are two primary ways to run the test suite. First, you can run the tests individually by visiting the different test pages associated with the area in which you are working. For example, to run the tests for `js/jquery.mobile.forms.slider.js` visit `$HOST/tests/unit/slider/`. To find out what which test pages are available you can list them with:
-* Rewrite (mod\_rewrite.so)
-* Expire (mod\_expires.so)
-* Header (mod\_headers.so)
+ grunt config:test:pages
-Alternatively, with the addition of async loading, you can use the python simple http server from the project root:
+Second you can run the tests using the [PhantomJS](http://phantomjs.org/) headless webkit browser which must be [installed](http://code.google.com/p/phantomjs/wiki/Installation). Once `phantomjs` is in the your `PATH` the following will execute the whole test suite:
- $ python -m SimpleHTTPServer 8000
+ JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$HOST grunt test
-And in your browser visit [localhost:8000](http://localhost:8000/tests/unit/core/). NOTE: The docs will not load as they are dependent on the "/js/" includes which require php. For other development work such as unit tests and custom test pages using
+You can confine the headless run to a single test page or set of test pages using the `TEST_PATH` environment variable. For example:
- <script data-main="js/jquery.mobile.docs" src="external/requirejs/require.js"></script>
+ TEST_PATH=slider JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
-will allow you to load modules asynchronously without php. Please note that the example above assumes it's inclusion in a page at the root of the directory in which the simple http server was run.
+Will only run the tests whos paths contain the string slider. *NOTE* That the phantom tests currently require that the webserver be running to access and run the tests properly because of the PHP dependency that many of them share.
-AMD Support in Development
-==========================
+Additionally we run the test suite against many version of jQuery using the `JQUERY` environment variable. For example if you wanted to run the test suite against both of our currently supported versions 1.6.4, and 1.7.1 the command would take the following form:
-Please bear in mind that async loading is not supported for production and is primarily used for the project's build process. As a result developers should expect an initial flash of unstyled content, which will not occur when the library is compiled.
+ JQUERY=1.6.4,1.7.1 JUNIT_OUTPUT=build/test-results/ ROOT_DOMAIN=$WEB_SERVER grunt test
-If you find dependency bugs when using the async loading support for development please log them in the github issue tracker.
+### Rebasing
-Building With A Custom Theme
-============================
-To use a custom theme in your own build, you'll need Make installed. You can find the themes in the CSS/Themes folder.
-To create a new theme:
-1. Copy the `Default` folder from CSS/Themes to a new folder in the same location. The name of the folder will be the
-theme's name. For testing locally, make sure the index.php file is copied as well.
-2. Edit the `jquery.mobile.theme.css` file so it contains your custom fonts and colors.
-3. Once you are done editing your files and saving them, open a terminal.
-4. Navigate to the jQuery-Mobile folder's root.
-5. Run the following command to build jQuery-Mobile (THEME is the name of the folder for your theme from step 1.):
- make THEME=YourThemeName
-6. The compiled files will be located in the "compiled" folder in the root of jQuery-Mobile.
View
45 build/tasks/config.js
@@ -26,14 +26,43 @@ module.exports = function( grunt ) {
});
});
+ grunt.registerTask( 'config:test:pages', 'glob and log all possible tests', function( a, b ) {
+ var test_paths = [], global_config = grunt.config.get( 'global' ), env = process.env;
+
+ // TODO move the glob to a legit config or pull the one from the qunit config
+ test_paths = glob.glob( 'tests/unit/*/' );
+ test_paths = test_paths.concat( glob.glob('tests/unit/**/*-tests.html') );
+
+ // append the jquery version query param where defined
+ var paths_with_jquery = [];
+ if( env.JQUERY ){
+ test_paths.forEach(function( full_path ) {
+ env.JQUERY.split( "," ).forEach( function( version ) {
+ paths_with_jquery.push(full_path + "?jquery=" + version);
+ });
+ });
+
+ test_paths = paths_with_jquery;
+ }
+
+ // if this test is not a dependency log pages
+ if( this.name.indexOf('config:test:page') > -1 ) {
+ test_paths.forEach(function( path ) {
+ grunt.log.writeln( path );
+ });
+ }
+
+ global_config.test_paths = test_paths;
+ grunt.config.set( 'global', global_config );
+ });
+
// TODO could use some cleanup. Eg, can we use grunt's parameter passing functionality
// in place of environment variables
grunt.registerTask( 'config:test', 'glob all the test files', function() {
var done = this.async(), test_paths, server_paths = [], env = process.env;
// TODO move the glob to a legit config or pull the one from the qunit config
- test_paths = glob.glob( 'tests/unit/*/' );
- test_paths = test_paths.concat( glob.glob('tests/unit/**/*-tests.html') );
+ test_paths = grunt.config.get( 'global' ).test_paths;
// select the proper domain + paths
test_paths.forEach( function( file_path ) {
@@ -46,18 +75,6 @@ module.exports = function( grunt ) {
}
});
- // append the jquery version query param where defined
- var paths_with_jquery = [];
- if( env.JQUERY ){
- server_paths.forEach(function( full_path ) {
- env.JQUERY.split( "," ).forEach( function( version ) {
- paths_with_jquery.push(full_path + "?jquery=" + version);
- });
- });
-
- server_paths = paths_with_jquery;
- }
-
grunt.config.set( 'qunit', { all: server_paths });
done();
});
View
2 grunt.js
@@ -185,7 +185,7 @@ module.exports = function( grunt ) {
grunt.loadNpmTasks( "grunt-junit" );
// A convenient task alias.
- grunt.registerTask('test', 'config:test junit');
+ grunt.registerTask('test', 'config:test:pages config:test junit');
// Ease of use aliases for users who want the zip and docs
grunt.registerTask('docs', 'js css legacy_tasks:docs');

0 comments on commit 2719b18

Please sign in to comment.