Are you considering to become a project-contributor?
We're happy you do! Being a project-contributor means you contibute more often and to more repositories of
ITSA-modules. You are basicly involved with the whole project. This could be the separate modules, this website or the main projectrepository that controls how to manages them all.
Anyone can become a projectcontributor, though we expect you to have a high level of programming skill, being a good teamplayer. Being a projectcontributor doesn't give you rights to make your changes go through to the project. The projectmanagers will always decide whether the code is accepted and conforms the goals of ITSA modules.
Important note:By making pull requests to ITSA's modules, you commit yourself that the code will be licensed under the New BSD License.
In order to manage the whole project, you need to download it all to your computer. This provides you several tools, which you can run locally, that makes it easy to manage and preview your changes. However, you cannot just download it all into one directory. There is a specific structure by which the documentation and api fall in the right place automaticly.
Before you follow the required installation-steps (explained below), you need to understand this treestructure, where the 3
itsa.modulename repositories have special meaning (more about that later):
We created installationsteps based on a linux or Mac system. Sorry if you have a Windows computer: in the future we will change all routines to run using Gulp.
Fork and clone
"Projectroot", which may be any directory-name of your choice. We advice you to call the directory
itsa.contributor. This repository is special: it is the startpoint to manage the project.
From within this directory, run
npm install. This will get all the packages required to do your local development.
Goto the directory
./sh and run:
sh initialsetup.sh which will create some symlinks you need to have for local testing. It also creates the directory
"Projectroot"/src which is the place to clone all ITSA's module-repositories (see next step).
Fork and clone all ITSA's repositories except
itsa.github.io. You must clone the repositories to
"Projectroot"/src/modulename where the directoryname equals the repository/modulename.
If you don't have them yet, install browserify, cssify and uglifyjs on your system globally: By installing it globally, their the command-line commands are available, which will be needed later on when creating the loaderfiles. `cssify` is also automaticly installed locally, for it needs to be there as well.
Because you also need the website (either for contribution, or to be able to preview documentation), you need to fork and clone
"Projectroot"/site. You must use the directoryname
site, otherwise local rendering will fail.
If you want to preview the site locally (with modified API or documentation), you need to install Jekyll. Jekyll is a static website generator, that is used by GitHub. We use it to generate our documentation using markdown.
From here, you need to follow these three steps:
Ruby language. If you have a Mac, you've most likely already got Ruby. If you open up the Terminal application, and run the command
ruby --versionyou can confirm this. Your Ruby version should begin with 1.9.3 or 2.0.0. If you've got that, you're all set. Otherwise, follow these instructions to install Ruby.
gem install bundler.
If you still experience troubles installing, then look here for help.
That was a bit of work, but it is worth it! You only need to do it once, hopefully it all went smoothless. Once installed, you can start working on the project (see below).
ITSA's polyfill has a polyfill for it. If not, then you should also add a polyfill. We think the Financial Times has nice polyfills (which we use directly, not as a service)
tests. We use Mocha with expect, should.js and chai assertion as Promises. Take a look at existsing test how to do this. Note: you must prevent
param.should.be.eql(number)for this fails in IE<10. Use
"Projectroot"/src. from within here, you run:
npm test modulenamewhere "modulename" is the name of the module/repository you want to test.
"Projectroot"/server. Goto this directory and run:
node server.js--> this will launch a server at
localhost:8000. Now from within any local browser you visit:
localhost:8000/test, which should present the testpage.
committhe code and make a
Commitand make a
After making changes, the website also needs to be changed. You always need to do this, because at the least, the version and file size of the module have changed.
After making changes, the website also needs to be changed. To make changes to the website, you need to understand a bit about github pages. Our website has the repository
itsa.github.io, this makes it directly visible at http://itsa.github.io, though we bound the CNAME itsa.io to it (which everyone visits).
The website from the repository
itsa.github.io is not a final website you can just see in the browser. It needs to be rendered first. GitHub does this using Jekyll (as explained above). If we want to view the website locally, we need to make this rendereing process ourselves. If you managed Step 7 above successfully, you can do this now: got to
"Projectroot" and run:
jekyll build --> this will create or update the folder
"Projectroot"/site-preview which is the website how it would be on GitHub-pages. You can inspect
"Projectroot"/site-preview/index.html in the browser now.
During modification, you will find out you want to re-render the website multiple times. Instead of doing this manually, you can run
jekyll build --watch, which will automaticly re-render on any changes.
All repositories have their own directory:
"Projectroot"/site/_docs/modulename where "modulename" is the name of the module/repository. Note the underscore: jekyll will transform this into a directoryname without underscore.
Every modulefolder has a markdown-file:
index.md. Whenever this file is present, it will appear in the list of available modules. This markdown-file should contain Front Matter, with the following definitions:
Some of these are optional.
To check the right filesize (minified an gzipped) we made a small bash-file: goto
"Projectroot"/sh and run:
sh checksize.sh modulename where "modulename" is the name of the module (or a specific filename inside its repository). This creates a temporarely minfied and gzipped file and output its size.
To get more familiair with creating documentation-files, inspect available documentation files: see how they are set up.
Any file other than
index.md is considered to be an example and should have the extention
.md. Whenever these files are present, they will automaticly appear below the
TOC as examples. The markdown-file should contain Front Matter, with the following definitions:
includeexamplehas a special meaning: it means there is a second file present but instead of
filename.mdits name is:
filename-incl.html. This is handy if you find out that your inline examples don't look right because of
css-bleedthrough: you can create a working-example that is included by an iframe. Most of the time you won't need to use this technique.
You may run into the situation where
"Projectroot"/site-preview uses the loaderfiles of the current site and hasn't updated with the changes you made at some repository. This is caused because life loaderfiles reside inside
"Projectroot"/site, which are transported to
"Projectroot"/site=preview with every jekyll build run. However, you can create loaderfiles of your local project: goto
"Projectroot"/sh and run:
sh preview.sh. Note that you need to do this every time after jekyll builds the website.