A pageviews analysis tool for Wikimedia Foundation wikis
This guide mostly assumes you're using OSX or Linux. The setup process may differ on Windows machines.
Sass will soon be replaced with Less to remove the Ruby dependency.
PHP is for rendering partials in the views and for the Intuition i18n framework. There otherwise is no backend logic.
The linters are not necessary, but preferred so your code maintains a consistent style.
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.
Create a copy of config.sample.php named config.php, and within that file, set ROOTDIR to your project root path.
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!
IE10 and Safari 8 and below are not supported.
All assets and views are ultimated placed in public_html. With the exception of images, you won't need to make any manual modifications to this directory.
The repo contains five separate applications that share code with each other (Pageviews, Langviews, Topviews, Siteviews and Massviews). The root directory of javascripts, stylesheets and views represent the Pageviews app. Other apps have a subdirectory therein. The main asset files share the same name as the app (e.g. pageviews.js for the main JavaScript file for Pageviews). Partials of any kind are prepended with underscores (e.g. _footer.php).
Each app has it's own config.js, which are constants for application-wide use. When the JS files are compiled, they are concatenated into a single application.js that lives within the directory for that app inside public_html. If you compile for non-production source maps will be included.
Shared JavaScript goes in the /shared directory and will be automatically included in each application.js.
All JavaScript is documented JSDoc. You can view the documentation by running:
grunt jsdoc && open doc/PageViews/1.0.0/index.html
Because of implications with concatenation, each SCSS file is first compiled into a file with the same name within public_html, and then concatentated into an application.css which is included in the views.
Each page has it's own .scss file that imports dependencies.
The views within /views are written in Haml and compiled to PHP files in /public_html. grunt watch can be configured to do this whenever you hit save on any view (same is true of JavaScript and Sass).
Run grunt pageviews for the main Pageviews app, or grunt topviews for Topviews, etc. To save time, you can run grunt browserify to compile only the JavaScript, grunt haml for the views, or grunt sass for the SASS.
Before making a pull request or pushing to master, remember to run grunt production so the assets are minified and concatenated.
Tests will be ran automatically when you push or create a pull request.
Prerequisites:
Once installed run java -jar selenium-server-standalone-2.52.0.jar to start the selenium server and ./nightwatch to run the tests. You can run specific tests like ./nightwatch --test tests/my_test.js.
If a test fails when you push to remote, check the build and there will be a link to a video of the test, along with the output of the logs.
The styling of all ES6 and SCSS is enforced with linters. You can run these locally with grunt lint, and will also be ran when you run grunt production. If for some reason you need a particular rule to be ignored, you can add exceptions (see Scss-lint, Eslint).