How to contribute to Okapi

Contributor License Agreement

Contributors must submit a signed Contributor License Agreement. This is a pretty common document in open-source projects.

See the Contributor License Agreement page for details and the document to fill.

Branching Model

The master branch is the latest release and is considered read-only except for critical hot fixes.

We do the development on the dev branch.

So any pull request must be done to the dev branch, after pulling the latest changes from the dev branch.

Git Settings

Several files (e.g. .bat and .sh) have specific types of line breaks that must remain the same. In general we try to handle this using .gitattributes, so that they should be independent of your settings.

But still, make sure your autocrlf setting is set to false on MacOS and Linux, and true on Windows.

After you clone the okapi repository, you can ensure that the autocrlf setting is set correctly by running this commnd:

git config core.autocrlf false

Building the Code

Okapi builds with Maven. You can build the entire project and execute all unittests by running:

mvn clean install

cd okapi/filters/xliff
mvn install

Running the Integration Tests

There are additional integration tests that don't run as part of the normal build. Once you've done a full maven install, the integration tests can be run like this:

mvn verify -f integration-tests -P integration

Building a distribution

Building a distribution will do a full rebuild of the project and run all unittests and integration tests, then generate a distribution package containing the Okapi tools in their final form.

WARNING: this part is outdated, needs updating! Might still work, but will soon change.

The distribution build scripts are located in deployment/maven, and are platform-specific:

• update-and-rebuild-linux.sh
• update-and-rebuild-linux64.sh
• update-and-rebuild-windows.sh
• update-and-rebuild-macosx.sh

The distribution will be built in a platform-specific directory called dist_[platform].

Note: Although these scripts do a full clean build, you must have run a regular mvn install from the top-level at least once at some point in the past, or else these scripts will throw an error. You don't need to do this every time.

For example, to build on the mac:

cd deployment/maven
# This produces output in the folder dist_cocoa-macosx-x86_64
./update-and-rebuild-macosx.sh

Working in Eclipse

TODO

Working in IntelliJ

TODO

Submitting a patch

The preferred method of submitting a patch is via pull request. To do this, you will need to do several things:

• Create your own fork of the okapi project on bitbucket. Bitbucket accounts are free to create, and you can create a fork by clicking "Fork" on the left nav-bar of the okapi project page.
• Clone your fork locally for development (or add it as a remote).
• Create a fix branch off of dev do implement your changes on.
• If you are committing changes that reference or fix an issue in the issue tracker, please include the issue number ("Issue #123") in the commit message. This will allow bitbucket to link the commit to the issue.
• Update changes.html if necessary (see below).
• Push your fix branch to your fork, and then open a pull request from your branch to the dev branch in the OkapiFramework/okapi repository.

Updating changes.html

Functional changes should be documented in the deployment/shared/changes.html file, grouped by release and functional area.

If your change is tied to an issue in the issue tracker, be sure to include the issue number here as well.