Skip to content

Latest commit

 

History

History
83 lines (46 loc) · 6.01 KB

CONTRIBUTING.md

File metadata and controls

83 lines (46 loc) · 6.01 KB
Raw

Contributing to TimelineJS

TimelineJS is open source software. Knight Lab appreciates contributions to the code and to the translations that support publishing timelines in other languages.

Please be aware that TimelineJS is designed to make digital storytelling simple. Historically, we've chosen not to pursue certain features which could be added to TimelineJS because we felt that they diverged from our design principles. If you have ambitious ideas for changes, you should start a conversation about the idea in GitHub issues using the "feature proposal" label.

Translations, bug fixes and features proposed and endorsed by Knight Lab should be contributed as GitHub pull requests.

If you run into challenges trying to set up for contribution, post a GitHub issue.

Working with the Code

The official way that TimelineJS code is managed uses a python-based system for compiling the javascript and CSS and managing the static site content. We strongly encourage people working on the code to use this system. However, if this is a major burden, it is also possible to use the CodeKit IDE to work on the code.

In order to clone or download the TimelineJS3 envrionment, use the following command:

git clone https://github.com/NUKnightLab/TimelineJS3.git

You must also check out one more git repository, that our code depends on. Check this out "alongside" your TimelineJS3 directory -- they should both have the same parent folder.

git clone https://github.com/NUKnightLab/fablib.git

The Python Method

Our build environment is routinely used with Python 2.7. Other versions of Python may work but have not been tested. Even though we call it the `python method`, there are also dependencies on `node` libraries for preparing the CSS and Javascript files.

Generally, we recommend python projects begin with a virtual environment (aka virtualenv) but this is not strictly required. Whether in a virtualenv or not, you must install a few libraries. The best way to do this is with the following command, after you cd into the TimelineJS3 folder:

pip install -r requirements.txt

Once the requirements are installed, here are things to know:

  • ALWAYS edit code in the /source/ directory. Pull requests which only have changes to code in the /build/ or /compiled/ directory are incorrect and will not be accepted.
  • use the fab build command to compile your changes for testing.
  • use the fab serve command to run a local web server which mimics the official documentation web site and provides a way to load your updated javascript for testing. The URL for your local test environment is http://localhost:5000/ You can use the make a timeline form with Google Spreadsheets to see how your changes are working. Remember: you must execute fab build after you change javascript to see your changes on your local server. It is not automatic.
  • You may also want to make sure that the examples still work as expected after you change code.
  • Don't break the unit tests. Consider adding test code for your changes. We're still working out our unit testing methodology, but before you submit pull requests, you should check http://localhost:5000/unit-tests.html and http://localhost:5000/mediatype-tests.html and verify that you haven't broken any of the tests with your changes.

Setting Up a Virtual Environment

To set up a virtual environment, you will first need to install virtualenv and virtualenvwrapper.

To install virtualenv, use the following command:

pip install virtualenv

To install virtualenvwrapper, first type the following command:

pip install virtualenvwrapper

Then, type this:

source /usr/local/bin/virtualenvwrapper.sh

Now, you can create a virtual environment with the following command:

mkvirtualenv timelinejs3

To activate the virtual environment, use the following command:

workon timelinejs3

node/npm

As mentioned above, developers building this code using Python must also install a handful of `node` utilities. Installing `node` and `npm` is left as an exercise for the developer, but once they are installed, make sure you do these commands: 
npm install -g less
npm install -g uglify-js
npm install -g less-plugin-clean-css

Check your install

Make sure that your virtual environment is active, change into your TimeLineJS3 directory and run these commands: 
fab build
fab serve

Then open a browser and visit http://localhost:5000/unit-tests.html . All of the unit tests should run with no errors reported. You may also want to check some of the examples, such as http://localhost:5000/examples/houston/ to make sure that things are basically working. The local webserver should load all of its javascript from your local /build/ directory, so as you develop code, periodically execute fab build and then use the local server to make sure things are going well. (Again, don't forget about the unit tests!)

Working with CodeKit

TimelineJS's initial development was done with CodeKit, so we maintain support for that.

Basically, just use CodeKit's "add project" feature to add the TimelineJS directory as a project. You shouldn't need to make any other changes. CodeKit is configured to build files automatically to the /compiled/ directory. There are HTML files in that directory designed to use for testing your code changes. The author of this document does not use CodeKit much, so if these instructions need improvement, please file a GitHub issue or give us a pull request.