Skip to content

Latest commit

 

History

History
150 lines (112 loc) · 8.14 KB

CONTRIBUTING.md

File metadata and controls

150 lines (112 loc) · 8.14 KB
Raw

Before writing code

  1. confirm issue is new
  • if not, get involved in previous report of issue
  1. create a new issue
  • this way, we can give feedback/direction as early as possible to ensure the most successful outcome for your hard work

Install Dependencies

Fuel UX uses npm and Grunt for development and maintenance tasks. You will need to install the required dependencies in order to contribute to Fuel UX.

In terminal from root directory of your fork of the fuelux repo:

  1. npm install
  2. bower install

Writing code

  • do not edit or commit files in the dist directory
    • project maintainers will commit files in the dist directory from time to time
    • details on compiling CSS and JavasScript can be found here
  • source files are in respective js, less, and fonts directories
  • conform to Salesforce Marketing Cloud style guide
  • if you are new to git, please review our git commit conventions
  1. fork this repository
  2. clone locally
  3. npm install
  4. create new branch, named after the GH Issue you are resolving
  5. add unit tests for new or changed functionality
  • unit tests are found in /test
  1. make your changes
  2. grunt test to lint and unit test your changes
  3. grunt servefast and visit http://localhost:8000/test/ for information on failing unit tests
  4. sync your fork with the upstream repo
  5. commit your changes
  • do not commit files within /dist
  • commit unit tests and code separately, unit tests first so we can see them fail and then pass
  • write meaningful commit messages (NO WIP!)

Grunt tasks

Run grunt --help or check out the Gruntfile to see all possible grunt tasks. When contributing, these are the grunt tasks you will be most likely to use:

Serving - grunt serve

Starts a watch server for automated javascript validation and basic tests (JSHint, simplified QUnit) allowing for prototyping at http://localhost:8000/ (not good for unit testing because server catastrophically fails if unit test fails).

Serving - grunt servefast

Starts a watch server allowing for prototyping at http://localhost:8000/ visual review of tests at http://localhost:8000/test/.

Testing - grunt test

Runs JSHint and full suite of QUnit tests.

Building dist - grunt dist

This builds the dist directory (compiling your CSS and JS). If you are going to issue a pull request, you should not include changes to the dist directory that are generated from this grunt task.

Submitting Pull Requests

All pull requests are validated via Travis CI. If the tests fail and you feel it is a Travis issue, you can trigger a restart.

While grunt can run the included unit tests via PhantomJS, this isn't a substitute for running tests across a variety of browsers and environments. Please be sure to test in as many of the browsers listed in sauce_browsers.yml as you can before contributing.

  1. run grunt test to lint & test your code
  2. if necessary, rebase and squash to as few commits as practical
  3. push to your forked repo
  4. submit a pull request to master
  1. Follow your pull request answering questions and making adjustments as appropriate until it is merged

QA

For more in-depth testing of Fuel UX, you can install Fuel UX on the gh-pages site, fuelux-dev.herokuapp.com, and the fuelux.herokuapp.com site.

Travis CI is run automatically for all Pull requests.

Running gh-pages locally

In addition to basic testing, using grunt test, you can compile the dist and manually place it into the docs site (in gh-pages branch) and test fuel ux out there.

Once you have checkout out the gh-pages branch and run npm install and bower install:

  1. If necessary, install Jekyll (requires v2.3.x).
  1. Install the Ruby-based syntax highlighter, Rouge, with gem install rouge.
  2. From the root /fuelux directory, run jekyll serve in the command line.
  3. Open http://localhost:9001 in your browser, and voilà.

FuelUX Dev

If you have permissions to the ExactTarget org on Heroku, you can get information on cloning the fuelux-dev remote from its app page on Heroku. If you do not have permissions and believe you should, please contact one of the FuelUX project maintainers.

A build of master is available at https://fuelux-dev.herokuapp.com/dist/js/fuelux.js and https://fuelux-dev.herokuapp.com/dist/css/fuelux.css.

These files should be considered unstable as this is our dev server

Sometimes people refer to FuelUX Dev as an "Edge Server". You can have your own edge server if you would like! To create one, setup a github web hook on Heroku for your fork of this repository and put the app into development mode with heroku config:set NPM_CONFIG_PRODUCTION=false.

Travis CI

Pull requests are validated via Travis CI.

Periodically pull requests may fail Travis CI build integration testing with a false negative. If you suspect this is the case you can restart the test via the command line (see below).

Travis downloads the node_modules folder from the "Edge" server ("fuelux-edge") hosted on Heroku. If you add or update a dependency in package.json, you will need to also update package.json in master locally and push it to Heroku for the dependency errors to be resolved in Travis.

Installing Travis CI Client locally

Travis requires ruby and the appropriate ruby gem.

Restarting a Travis CI Build

From the Browser

  1. On the Pull Request page on Github, click on the "details" link in the Travis CI build area
  2. Click "Login with Github" at the top right of the page
  3. Click the "Restart Build" button (circular button with an arrow going in a circle)

From the Command Line

  1. Login to Travis In the terminal, issue the following command (You'll need to use your Github credentials):

    travis login --org

  2. Acquire build number In the terminal, issue the following command:

    travis history

  3. Restart Build using the build number you obtained from travis history In the terminal, issue the following command:

    travis restart 9999