Wiki
Clone wikiOkapi / How to Contribute
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
okapi
directory. The maven install
phase will install the compiled Okapi libraries in your local maven repository, allowing you to subsequently build individual sub-projects:
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.
Updated