Pageviews Analysis
A pageviews analysis tool for Wikimedia Foundation wikis
Dependencies
This guide mostly assumes you're using OSX or Linux. If that's the case, you can probably already have Ruby. Try in your terminal with ruby -v. If you are only updating the JavaScript (where all the logic lives), you don't need Ruby or Sass. Even for Sass, you could update the source and use an online converter to update the compiled version, then just run grunt concat to correctly concatenate those files for production use.
The linters are not necessary, but preferred so your code maintains a consistent style.
Compilation
This first time around you'll need to install all node pacakges and dependencies with npm install. You'll also need to install Composer and run composer update.
Local
Run grunt pageviews for the main pageviews app. To save time, you can run grunt sass to just compile the SCSS.
If you're only working with the JavaScript, and don't want to deal with Ruby dependencies (SASS), just run grunt browserify. Then when you're done with your work run grunt concat and grunt uglify to make your code production-ready.
Production
Before making a pull request or pushing to master, remember to run grunt production so the assets are minified and concatenated.
Implementation approach
This app aims to be a part of the future and not linger in the past. JavaScript is written in ES6
where possible, and compiled to ES5 with Babel when you run Grunt. If you need to add a polyfill for
something, add it to /javascript/shared/polyfills.js. Don't use jQuery utilities when native JavaScript can do it.
For CSS don't worry about adding vendor prefixes to anything in the CSS3 spec. If it works in Chrome and Firefox, leave it at that. Other browsers will still function without the styling. Use Bootstrap classes if possible.
Browserify is used to help follow a module pattern. You'll need to require('./file_name') any file that is a dependency.
JSDoc is the preferred comment format. Try to document each function you create. The linters will complain if you don't!
IE9 and below are not supported.
Tests
Right now all we have for tests are the linters... you can run those with grunt lint or npm test. They will be ran automatically when you push or create a pull request. If for some reason you need a particular linter rule to be ignored, you can add exceptions (see Scss-lint, Eslint).
Moving forward we'll look into integration/automated testing, as unit tests don't seem to be the most fitting for this application.