From a93444179f9d529ed085f9bba8616d602937de43 Mon Sep 17 00:00:00 2001 From: rosekaron Date: Tue, 24 Jun 2014 17:23:01 +0800 Subject: [PATCH 1/7] Update index.md.hbs grammar, sentence construction and the use of a firm but friendly tone. Please dig out the discussion forum links so as I can add it in the next PR. --- templates/pages/contrib/index.md.hbs | 37 ++++++++++++++++------------ 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/templates/pages/contrib/index.md.hbs b/templates/pages/contrib/index.md.hbs index 8996e7b..10aa070 100644 --- a/templates/pages/contrib/index.md.hbs +++ b/templates/pages/contrib/index.md.hbs @@ -4,31 +4,36 @@ section: development title: Contribution Guideline --- -> Feeling like part of this Troop? Here's how you can contribute. +> Thank you for your interest in contributing to TroopJS. We value and welcome everyone's opinion so in order to encourage you, we'll try to make the guidelines simple and sweet. -## Questions +##Let us hear your pain. -We love questions, and we love knowing how you're using TroopJS. Please create a new issue in TroopJS's -revelant modules repositories, e.g. [troopjs-core](https://github.com/troopjs/troopjs-core) but not in -the bundle [repository](https://github.com/troopjs/troopjs) unless it truely cannot fall into any of the existing modules. +Most of the modules that's been added to the TroopJS framework are a result of feedback gathered from our early adopters. Help us make TroopJS work for you by [letting us hear your pain](https://github.com/troopjs/troopjs/issues/new). Remember to be nice and say please. -## Reporting issues +##Satisfied with TroopJS? -Please read the following guidelines before opening any issue. +Good. [It will be wonderful if you can tell us why](https://github.com/troopjs/troopjs/issues/new). + +##Questions/ Discussions? + +Please visit our discussion forum. -1. **Search for existing issues.** To avoid duplicate issues, it would help us out if you could please check first to see if someone else has reported the same issue. Moreover, the issue may have already been resolved with a fix available. -2. **Create an isolated and reproducible test case.** Be sure the problem exists in TroopJS's code with a [reduced test case](http://css-tricks.com/reduced-test-cases/) that should be included in each bug report. -3. **Include clear examples.** Make use of jsFiddle or jsBin to share your isolated test cases. -4. **Share as much information as possible.** Include version of Assemble, customized or vanilla build, etc. where appropriate. Also include steps to reproduce the bug. +## Reporting an issue + +Please read the following guidelines before opening any issue. +1. **Search for existing issues.** Creating duplicate issues not only wastes your time, it slows us down too because it adds unnecessary admin work. Before you create an issue, check if the issue you are about to report already exists or if it's been resolved with a fix available. +2. **Create isolated and reproducible test cases.** To ensure that the problem exists in TroopJS's code by building a [reduced test case](http://css-tricks.com/reduced-test-cases/). +3. **Include clear examples.** Make use of jsFiddle or jsBin when you share your isolated test cases. +4. **Share as much information as possible.** Include version of Assemble, customized or vanilla build, etc. where appropriate. ## Pull requests -* Pull requests for each TroopJS module shall be rebased against the head of the `develop` branch -* Please refer from the PR to an existing issue to be explainatory -* Associated tests shall be included as part of the pull request changes. -* Changes shall follow our existing coding style especially in indentation and qutations -* Try not to pollute your pull request with unintended changes--keep them simple and small +* Pull requests for each TroopJS module will be rebased against the head of the `develop` branch. +* Reference an existing issue with your pull requests to be explanatory. +* Associated tests will be included as part of the pull request changes. +* Changes should follow our existing coding style especially indentation and quotations. +* Try not to pollute your pull request with unintended changes--keep them simple and small. ## Coding Style From 631ed1bbebecad7656194d13a7b0fe18e8fbe641 Mon Sep 17 00:00:00 2001 From: rosekaron Date: Tue, 24 Jun 2014 18:45:06 +0800 Subject: [PATCH 2/7] Update bundle.hbs WIP --- templates/pages/contrib/bundle.hbs | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/templates/pages/contrib/bundle.hbs b/templates/pages/contrib/bundle.hbs index 1e5bd15..72ca279 100644 --- a/templates/pages/contrib/bundle.hbs +++ b/templates/pages/contrib/bundle.hbs @@ -4,40 +4,40 @@ section: development title: TroopJS Bundle --- -> The TroopJS bundle is the deck bearing all rest of modules, -> which serves various different aspects of development tasks, from creating release files to generating API docs. +> The TroopJS bundle is the deck that bears all modules +> that serves various aspects of development tasks-- from creating release files to generating API docs. -TroopJS unlike many other singular libraries, is a highly modularized framework consist of many small, dedicated modules -that works side-by-side with certain dependencies on each other. The bundle repository instead has no actual functional module, -but only to glue a selected group of modules together for development and release purpose, thus setup the bundle is the -initial step of TroopJS development. +TroopJS, unlike many other singular libraries, is a module-based framework consisting of small, dedicated modules that work side-by-side with certain dependencies with each other. The bundle repository has no actual functional module in it, +and is there mainly to glue a selected group of modules together for development and release purpose. Thus setting up the bundle is the +initial step for TroopJS development. -## Setup the bundle -clone the bundle [repository](https://github.com/troopjs/troopjs) first: +## Setting up the bundle + +Clone the bundle [repository](https://github.com/troopjs/troopjs): ```shell git clone https://github.com/troopjs/troopjs cd troopjs ``` -To install the list of default modules from bower, only core modules will be included as default +To install the list of default modules from bower: ```shell bower install ``` -All core modules should now reside in the `bower_components` directory, this install will also include those 3rd libraries -that individual module relies on. +NOTE: Only core modules will be included by default. + +Modules should now reside in the `bower_components` directory, this install will also include third party libraries that individual module rely on. ## Build with Grunt -TroopJS uses [grunt](http://gruntjs.com) as the build system, first make sure grunt and all grunt task plugins are installed via NPM. +TroopJS uses [grunt](http://gruntjs.com) for its build system. Make sure grunt and all grunt task plugins are installed via NPM. ```shell npm install ``` -Check for available grunt tasks by `grunt --help` which gives you the list of grunt tasks that powers TroopJS, some primary -ones are explained below: +Check for available grunt tasks by using `grunt --help` which should give you the list of grunt tasks available. Below is a brief description of the most commonly used tasks: * compile - This task takes different profiles (right now `maxi` and `mini`) defined in each a list of included modules, to trace individual ones for it's module dependencies, eventually put together the bundled script will all modules by requirejs From 79e6fe3c9b02f99b53f177b776dbcec1377b4d8a Mon Sep 17 00:00:00 2001 From: rosekaron Date: Wed, 25 Jun 2014 11:16:58 +0800 Subject: [PATCH 3/7] Update bundle.hbs WIP --- templates/pages/contrib/bundle.hbs | 34 ++++++++++++++++-------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/templates/pages/contrib/bundle.hbs b/templates/pages/contrib/bundle.hbs index 72ca279..63301d6 100644 --- a/templates/pages/contrib/bundle.hbs +++ b/templates/pages/contrib/bundle.hbs @@ -7,9 +7,8 @@ title: TroopJS Bundle > The TroopJS bundle is the deck that bears all modules > that serves various aspects of development tasks-- from creating release files to generating API docs. -TroopJS, unlike many other singular libraries, is a module-based framework consisting of small, dedicated modules that work side-by-side with certain dependencies with each other. The bundle repository has no actual functional module in it, -and is there mainly to glue a selected group of modules together for development and release purpose. Thus setting up the bundle is the -initial step for TroopJS development. +Unlike many other singular libraries, TroopJS is a framework that consists of small, dedicated modules that work side-by-side, with certain dependencies with each other. The bundle repository has no actual functional module in it. +It's there to glue a selected group of modules together for development and release purpose. For this particular reason, setting up the bundle is required for TroopJS development. ## Setting up the bundle @@ -27,7 +26,7 @@ bower install NOTE: Only core modules will be included by default. -Modules should now reside in the `bower_components` directory, this install will also include third party libraries that individual module rely on. +Modules should now reside in the `bower_components` directory, this install will also include third party libraries that individual modules rely on. ## Build with Grunt @@ -36,24 +35,27 @@ TroopJS uses [grunt](http://gruntjs.com) for its build system. Make sure grunt a ```shell npm install ``` +Below is a list of the most commonly used tasks with its description: -Check for available grunt tasks by using `grunt --help` which should give you the list of grunt tasks available. Below is a brief description of the most commonly used tasks: + * compile - The compile task takes different profiles defined in the list (`maxi` and `mini`) of included modules to trace its module dependencies, eventually putting together the bundled script with all modules by requirejs [optimizer](http://requirejs.org/docs/optimization.html). The uncompressed results bundle will be created in `dist` directory. - * compile - This task takes different profiles (right now `maxi` and `mini`) defined in each a list of included modules, -to trace individual ones for it's module dependencies, eventually put together the bundled script will all modules by requirejs -[optimizer](http://requirejs.org/docs/optimization.html). The results bundle uncompressed will be created in `dist` directory. - * test - This task is to run every module's tests with the buster runner backed by phantomJS, tests will be run from command -line in the head-less browser, fails the task in case any of the tests has failed, and to log rest report on standard output. - * release - This task is to perform TroopJS release from the current branch, which create TroopJS bundle from the above `compile` -task, eventually compress it and push the `dist` directory content to an orphan release branch corresponds to the current version. - * docs - This task generates and assembles JSDuck API documentation for all modules found within the `bower_components` directory. - * version - This task manages TroopJS versioning with Git tag in semver compliant format. - * eslint - This task lint for all modules sources found within `bower_components` directory with eslint(http://eslint.org/) rules. + * test - The test task is used to run every module's tests using the buster runner backed by phantomJS. Tests are run using a command +line in the head-less browser. The task fails in case any of the tests fails. In which case, it then logs a rest report on the standard output. + * release - The release task is used to perform TroopJS releases from the current branch. This will create a TroopJS bundle from the above `compile` +task, compress it and then, push the `dist` directory content to an orphan release branch corresponding to the current version. + + * docs - The docs task generates and assembles JSDuck API documentation for all modules found in the `bower_components` directory. + + * version - The version task manages TroopJS versioning with Git tag in [semver](http://http://semver.org/) compliant format. + + * eslint - The eslint task lints all modules sources found within the `bower_components` directory using eslint(http://eslint.org/) rules. + +NOTE: To see a full list of grunt tasks available, use `grunt --help`. ## Test with Buster.JS -TroopJS tests are written and run in [Buster.JS](http://docs.busterjs.org/), all tests can be running in any of the following ways: +TroopJS tests are written and run in [Buster.JS](http://docs.busterjs.org/). All tests can be run through any of the following ways: - opening web page with either static browser runner that runs tests in a browser - directly through command line with headless browser like phantomJS From 6fb1094496ee1b2d2510723edff658effa1ccc17 Mon Sep 17 00:00:00 2001 From: rosekaron Date: Wed, 25 Jun 2014 12:12:43 +0800 Subject: [PATCH 4/7] Update bundle.hbs wip --- templates/pages/contrib/bundle.hbs | 43 ++++++++++++++++-------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/templates/pages/contrib/bundle.hbs b/templates/pages/contrib/bundle.hbs index 63301d6..c772e97 100644 --- a/templates/pages/contrib/bundle.hbs +++ b/templates/pages/contrib/bundle.hbs @@ -35,69 +35,72 @@ TroopJS uses [grunt](http://gruntjs.com) for its build system. Make sure grunt a ```shell npm install ``` -Below is a list of the most commonly used tasks with its description: +Below is a list of the most commonly used tasks with their descriptions: - * compile - The compile task takes different profiles defined in the list (`maxi` and `mini`) of included modules to trace its module dependencies, eventually putting together the bundled script with all modules by requirejs [optimizer](http://requirejs.org/docs/optimization.html). The uncompressed results bundle will be created in `dist` directory. + * compile - The compile task takes different profiles (`maxi` and `mini`) that define lists of included modules to trace its module dependencies, eventually putting together the bundled script with all modules by requirejs [optimizer](http://requirejs.org/docs/optimization.html). The uncompressed result bundle will be created in the `dist` directory. - * test - The test task is used to run every module's tests using the buster runner backed by phantomJS. Tests are run using a command -line in the head-less browser. The task fails in case any of the tests fails. In which case, it then logs a rest report on the standard output. + * test - The test task is used to run every module's tests using the buster runner backed by phantomJS. Tests are executed from the command +line using a head-less browser. The task fails if any of the tests fails, in which case, it then logs a rest report on the standard output. * release - The release task is used to perform TroopJS releases from the current branch. This will create a TroopJS bundle from the above `compile` task, compress it and then, push the `dist` directory content to an orphan release branch corresponding to the current version. - * docs - The docs task generates and assembles JSDuck API documentation for all modules found in the `bower_components` directory. + * docs - The docs task generates and assembles JSDuck API documentation for TroopJS modules. * version - The version task manages TroopJS versioning with Git tag in [semver](http://http://semver.org/) compliant format. - * eslint - The eslint task lints all modules sources found within the `bower_components` directory using eslint(http://eslint.org/) rules. + * eslint - The eslint task lints all TroopJS sources using eslint(http://eslint.org/) rules. NOTE: To see a full list of grunt tasks available, use `grunt --help`. ## Test with Buster.JS -TroopJS tests are written and run in [Buster.JS](http://docs.busterjs.org/). All tests can be run through any of the following ways: +TroopJS tests are written in [Buster.JS](http://docs.busterjs.org/). All tests can be executed through any of the following ways: - - opening web page with either static browser runner that runs tests in a browser - - directly through command line with headless browser like phantomJS - - simultaneously run tests on all the captured browsers + - opening a web page using any static browser runner that runs tests in a browser + - directly through a command line using a headless browser like phantomJS + - simultaneously running tests on all captured browsers -Run tests with phantomJS is the simpliest way of verying all tests are green, which is available as grunt task `test`, -if it's your first time of running this command buster and phantomJS will be installed which will take a while. +NOTE: Out of the methods above, we are inclined to recommend executing the tests using phantomJS as it's available as a grunt task (`test`). Furthermore, it proves to be the simplest way of verifying that all tests are green. + +Running the buster command below will install phantomJS (if it is your first time to do so). Installation might take a while. Patience is a virtue. ```shell grunt test ``` -Run only specific tests statically in one browser is handy for debugging and trouble shoot test failures, launch `buster-static` -and point your browser to printed runner URL. +Executing specific tests statically in one browser is handy for debugging and trouble shooting test failures. Do so by launching `buster-static` +and pointing your browser to the printed runner URL. ```shell buster-static Starting server on http://localhost:8282/ ``` -You can also specify glob pattern that filters down the tests further and to run only those tests, e.g. the following -is to run only tests from `troopjs-core` module. +You may also specify a glob pattern that will allow you to execute a specific test within a filtered module. + +Below is a sample that illustrates how a specific test is run on a filtered module (`troopjs-core`). ```shell buster-static -t "/Users/garry/workspace/troopjs/bower_components/troopjs-core/test/**/*.js" ``` -To run tests simutaneously with captured browsers you should instead launch `buster-server`, open the runner page with -your concerned browsers and click for "capture". +To run tests simultaneously on captured browsers, you may launch `buster-server`. Open the runner pag, specify your captured browser and click "capture". ```shell buster-server buster-server running on http://localhost:1111 ``` -Then you can run tests from command line like the above with static runner. +You can then run tests using a command line like so with a static runner: ```shell buster-static -t "/Users/garry/workspace/troopjs/bower_components/troopjs-core/test/**/*.js" ``` -When adding more tests be aware that all tests shall be within the `test` directory for each module, each subjected component +NOTE: If you want to add tests, please follow these guidelines: + +- be aware that all tests shall be within the `test` directory for each module, each subjected component shall has a corresponding test suite file of it's own, filename must be suffixed by `-test`, for instance the test suite file for `troopjs-browser/component/widget` would be `troopjs-browser/test/component/widget-test`. From 4cdc83a2ab680da7400b05e80ad143687c46e2fd Mon Sep 17 00:00:00 2001 From: rosekaron Date: Wed, 25 Jun 2014 12:32:49 +0800 Subject: [PATCH 5/7] Update bundle.hbs wip --- templates/pages/contrib/bundle.hbs | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/templates/pages/contrib/bundle.hbs b/templates/pages/contrib/bundle.hbs index c772e97..83f1f0f 100644 --- a/templates/pages/contrib/bundle.hbs +++ b/templates/pages/contrib/bundle.hbs @@ -85,28 +85,26 @@ Below is a sample that illustrates how a specific test is run on a filtered modu buster-static -t "/Users/garry/workspace/troopjs/bower_components/troopjs-core/test/**/*.js" ``` -To run tests simultaneously on captured browsers, you may launch `buster-server`. Open the runner pag, specify your captured browser and click "capture". +To run tests simultaneously on captured browsers, you may launch `buster-server`. Open the runner page with browser of choice and click "capture". ```shell buster-server buster-server running on http://localhost:1111 ``` -You can then run tests using a command line like so with a static runner: +You may also run tests using a command line like so with a static runner: ```shell -buster-static -t "/Users/garry/workspace/troopjs/bower_components/troopjs-core/test/**/*.js" +buster-static -t "./bower_components/troopjs-core/test/**/*.js" ``` -NOTE: If you want to add tests, please follow these guidelines: +NOTE: If you want to add more tests, please follow these guidelines: -- be aware that all tests shall be within the `test` directory for each module, each subjected component -shall has a corresponding test suite file of it's own, filename must be suffixed by `-test`, for instance the test suite file -for `troopjs-browser/component/widget` would be `troopjs-browser/test/component/widget-test`. +- All tests are located in the `test` directory of each module. Each component +has a corresponding test suite file of its own. Use the suffix `-test` when you name files (example: the test file for `troopjs-browser/component/widget` is named `troopjs-browser/test/component/widget-test`). -If in your tests other dependent scripts are to be required, they have to appear inside the `libs` or `resources` -section of `test/buster.js` of [buster configuration](http://docs.busterjs.org/en/latest/modules/buster-configuration/) -to make them available at runtime. +If your tests are dependent on script/s, the script/s have to appear inside the `libs` or `resources` section of `test/buster.js` of [buster configuration](http://docs.busterjs.org/en/latest/modules/buster-configuration/) +so as to make them available at runtime. You may want to check individual module source for more details of how does TroopJS buster test case looks like. From 6c50d4ae988ffb092233df6d3e9a4a3e4fab990f Mon Sep 17 00:00:00 2001 From: rosekaron Date: Wed, 25 Jun 2014 15:34:17 +0800 Subject: [PATCH 6/7] Update bundle.hbs --- templates/pages/contrib/bundle.hbs | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/templates/pages/contrib/bundle.hbs b/templates/pages/contrib/bundle.hbs index 83f1f0f..def32df 100644 --- a/templates/pages/contrib/bundle.hbs +++ b/templates/pages/contrib/bundle.hbs @@ -106,17 +106,15 @@ has a corresponding test suite file of its own. Use the suffix `-test` when you If your tests are dependent on script/s, the script/s have to appear inside the `libs` or `resources` section of `test/buster.js` of [buster configuration](http://docs.busterjs.org/en/latest/modules/buster-configuration/) so as to make them available at runtime. -You may want to check individual module source for more details of how does TroopJS buster test case looks like. +We also suggest that you check individual module source for more details of how TroopJS buster test cases look like. -## Build profile +## Aggregate modules -Bundle profiles currently `maxi.js` and `mini.js` are preset list of modules to be included in a requirejs -[optimizer](http://requirejs.org/docs/optimization.html) run, all troopjs modules but not external ones will be bundled -as a whole, with an extra `troopjs/version` module which indicates exact version of troopjs. +The modules `maxi.js` and `mini.js` are aggregate modules used by the requirejs [optimizer](http://requirejs.org/docs/optimization.html). TroopJS bundles will be created together with a `troopjs/version` module which indicates the version of TroopJS. -If you're not satisfied with our preset list of modules in bundle, you can easily build you own bundle by modifying -one of the existing bundle profile then just to rebuild, to examplify we redefine how the `maxi` bundle looks like by -removing some unused modules from `troopjs-data`, and add some interested widgets from the `troopjs-contrib-browser` package. +If you're not satisfied with our aggregate modules, you can easily create your own bundle by modifying +one of the existing aggregate modules or just create a new one. For example, we can redefine how the `maxi` bundle look like by +removing some unused modules from `troopjs-data`, and adding some interesting modules from the `troopjs-contrib-browser` package. ```js define([ @@ -132,10 +130,10 @@ define([ }); ``` -Before rebuild the bundle, we need to make sure the new `troopjs-contrib-browser` package is properly installed locally. +Before building the bundle, we need to make sure the new `troopjs-contrib-browser` package is installed locally. ``` bower install troopjs-contrib-browser --save-dev ``` -Then to rebuild you bundle with `grunt compile` and we should be able to check the updated list of bundled modules in `dist/build.txt` file. +Then, build your bundle with `grunt compile` and you should be able to check the updated list of bundled modules in the `dist/build.txt` file. From 5528f37a3c2d1cb88fb8c81fd23bee5eebbcd78a Mon Sep 17 00:00:00 2001 From: rosekaron Date: Wed, 25 Jun 2014 15:57:01 +0800 Subject: [PATCH 7/7] Update index.md.hbs WIP --- templates/pages/contrib/index.md.hbs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/pages/contrib/index.md.hbs b/templates/pages/contrib/index.md.hbs index 10aa070..26cf144 100644 --- a/templates/pages/contrib/index.md.hbs +++ b/templates/pages/contrib/index.md.hbs @@ -24,7 +24,7 @@ Please read the following guidelines before opening any issue. 1. **Search for existing issues.** Creating duplicate issues not only wastes your time, it slows us down too because it adds unnecessary admin work. Before you create an issue, check if the issue you are about to report already exists or if it's been resolved with a fix available. 2. **Create isolated and reproducible test cases.** To ensure that the problem exists in TroopJS's code by building a [reduced test case](http://css-tricks.com/reduced-test-cases/). -3. **Include clear examples.** Make use of jsFiddle or jsBin when you share your isolated test cases. +3. **Include clear examples.** Make use of jsFiddle, jsBin or gist when you share your isolated test cases. 4. **Share as much information as possible.** Include version of Assemble, customized or vanilla build, etc. where appropriate. ## Pull requests