Development Process

This document describes how development will proceed in ilib.

Who Can Contribute

Any developer that has knowledge of international issues and would like to contribute may do so. All code will be code reviewed by the project admin. Simply email to marketing@jedlsoft.com to request to be added to the list.

Unit Tests

Any changes to ilib will not be accepted into trunk without thorough unit testing, even if they appear to work correctly. Unit tests form a regression suite that can be used to make sure that major changes to ilib will not break existing APIs.

The set of tests for a feature must include both positive tests (tests that things work as expected) and negative tests (tests that the code can deal with bogus inputs).

ILib uses a simple JUnit test framework to test code. The same tests can be run in browsers or on the command-line in nodejs.

Unit Tests in Browsers

To run code in a browser, first make sure that your browser allows pages to read files from the local file system. For Chrome, for example, you must start chrome with some special options. Here's how you start it on linux:

/usr/bin/google-chrome-stable --allow-file-access-from-files --disable-web-security

In Firefox, you must follow the directions in this page to allow it to read local files.

Once you have done that, you can open a new page in your browser and direct it to tools/jsunit/testRunner.html inside of your ilib checkout directory. If you have done the above correctly, you should see an input box where you can type the path to an html file. Each test directory should have a testSuite.html inside of it that will run all the tests using this test runner. Try "/path_to_your_ilib_checkout/js/src/calendar/test/testSuite.html" for example. The progress bar will show how the tests are progressing.

Unit Tests on the Command-Line

You can run the unit tests on the command-line or via the ant file. To get this to work, nodejs 0.12 or earlier must be installed, and the nodejs executable must be in your executable path. This is "node.exe" on Windows or "node" for other OS's.

The easiest way to run the tests is via ant. To run all the tests:

ant test.dynamic.compiled

To run tests in a particular packages:

ant test.calendar test.date

Branches and Trunk

The trunk is where all mainline builds should be shipped from. It should be in a shippable condition at all times. That means that all unit tests should pass 100% before you check in things to the trunk. On rare occasions, a branch has to be made from trunk to backport a change to an earlier version.

For development items that are short, you can check out the trunk, do your work, and then check in there as long as you have added unit tests to test your work and all tests pass.

For development work that is longer term, you must make a branch in the branches folder. The branch name is not that important. You may check in changes to the code or unit tests that do not pass 100% so that you can co-ordinate unfinished changes between machines or developers. When the feature is done, unit tests have been added and they all pass 100%, it should be merged back to trunk and the branch should be declared ended. All code must be code reviewed by the project admin before it can be merged to trunk.

Releases

Releases progress linearly. Major releases increment the number before the dot, and minor releases increment the number after the dot. The build number forms the third part of the release number, and is mostly used to distinguish builds from each other.

Major Release: any time a major feature is added or reworked, it should cause an increment in the major release number. Typically, there are a number of builds in a major release to stabilize the new feature.

Minor Release: if no major features are added or reworked, but a crashing or high priority bug is fixed, a minor release should be issued to make sure that the public gets the benefit of the bug fix as soon as possible. The minor release increments the number after the release eg. 5.0 -> 5.1. Minor release are infrequent.

We will not make special releases for bug fixes that are lower priority. These will typically be released in the major release builds.

The current release number is considered unstable/in-development until all the major features and bugs are complete and it has been tested and accepted for a while. When the team is satisfied that it is stable enough, it will be designated as the "latest stable" release, and the major release number will be incremented for the next development version.

In order for the last build of a release to be accepted and become the "latest stable", it must pass all unit tests in nodejs on the command-line, and in the latest versions of Chrome, Opera, Firefox, and Internet Explorer. Typically, these browsers are tested both on Windows and Ubuntu Linux. Infrequently, the tests are run on rhino, on older versions of browsers, and on browsers running on MacOS in order to preserve the compatibility for these platforms.

Backwards Compatibility

ILib maintains backwards compatibility in the APIs where-ever possible. That is, the APIs for every major release should accept the same API as previous releases. The idea is that code that is using an older version of ilib should continue to run with reasonable results without modification when upgraded to use a newer version of ilib.

Backwards compatibility means that parameters, methods, and functions should not be removed, although they may become ignored or deprecated. New parameters to functions and methods may be added at the end of the parameter list, and new options may be added to option blocks that are used in constructors. Also, new methods may be added to classes.

As well, the behaviour of functions and methods may change so that they produce different output than before. The type of the output should remain the same though. That is, a function that returns a string must always return a string, though the contents of the string may vary per release.

If there needs to be a change to an API instead of an addition, a new function/method should be added instead with the corrected API. Where possible, the old API should be re-implemented as a wrapper around the corrected API so that it can take advantage of the correction. If it is not possible, the old API can continue to return the previous output, and the API should be marked as @deprecated in the inline docs.