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.

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):

Installation-steps

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.

Step 1:

Fork and clone itsa.contributor to "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.

Step 2:

From within this directory, run npm install. This will get all the packages required to do your local development.

Step 3:

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).

Step 4:

Fork and clone all ITSA's repositories except itsa.contributor and itsa.github.io. You must clone the repositories to "Projectroot"/src/modulename where the directoryname equals the repository/modulename.

Step 5:

If you don't have them yet, install browserify, cssify and uglifyjs on your system globally:

npm install -g browserify
npm install -g cssify
npm install -g uglify-js

Step 6:

Because you also need the website (either for contribution, or to be able to preview documentation), you need to fork and clone itsa.github.io to "Projectroot"/site. You must use the directoryname site, otherwise local rendering will fail.

Step 7:

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:

• You need Ruby - Jekyll requires the 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 --version you 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.
• You need Bundler - Bundler is a package manager that makes versioning Ruby software like Jekyll a heck of a lot easier if you're going to be building GitHub Pages sites locally. If you don't already have Bundler installed, you can install it by running the command gem install bundler.
• Now you have both Ruby and Bundler, you can install Jekyll very easy: from inside "Projectroot" you run: bundle install

If you still experience troubles installing, then look here for help.

Finished!

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).

Changes to a repository

• Make the changes, update the module-version inside package.json
• Update the historyfile: site/_docs/modulename/history.md
• Make sure the API is updated (when needed)
• Check if you include any code that might not match our targetted browsers (IE8+ and all modern browsers). If you do, then check if 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)
• Add tests inside the folder 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 expect(param).to.be.eql(number) instead.
• Test your tests in nodejs and any browser you have available:
  • To test inside nodejs, you go to the directory "Projectroot"/src. from within here, you run: npm test modulename where "modulename" is the name of the module/repository you want to test.
  • To test on the browsers, you need to setup a testserver, which is included in "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.
• If all tests pass, you commit the code and make a pull request.
• You also need to rebuild the distribution files

Always update the repository itsa.build

• Update the module-version inside package.json of itsa.build
• Update the documentation: set a new version and filesize
• Update the historyfile: site/_includes/history.html
• Rebuild the loader-files: goto "Projectroot"/sh and run: sh production.sh
• Commit and make a pull request for itsa.build.

Always changes to website-documentation

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.

Documentation of the repository:

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:

• module: xxxxx
• itsaclassname: xxxxx
• version: xxxxx
• modulesize: xxxxx
• dependencies: xxxxx
• maintainer: xxxxx
• title: xxxxx
• intro: xxxxx
• firstpar: xxxxx

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.

Examples inside the repository:

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:

• module: xxxxx
• maintainer: xxxxx
• title: xxxxx
• intro: xxxxx
• includeexample: xxxxx

Up to date build-files for the examples inside "Projectroot"/site-preview:

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.