First off, thanks for taking the time to contribute! Your efforts are much appreciated.
This project is the InfoArchive Software Development Kit (SDK). Its purpose is to make it easy to write applications that connect with OpenText InfoArchive. It does NOT contain code for InfoArchive itself, since that is not open source.
You should be familiar with InfoArchive concepts. Please read through the InfoArchive documentation, or at least take a look at the lab project. In particular, you should be familiar with the concepts of Submission Information Package (SIP) and Preservation Description Information (PDI), as described by the OAIS Reference Model for digital preservation.
You need access to a running InfoArchive server to invoke some of the SDK’s functionality, like ingesting SIPs. Other functionality, like assembling SIPs, can be used without such access.
Reporting a bug helps ensure that the project works for as many people and in as many environments as possible.
Before creating a bug report, please check the existing issues as you might find that your problem is already reported. If you find an issue that is still open, add a comment to the existing issue instead of opening a new one. If you find a closed issue that seems like it is the same thing that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.
When creating an issue, be specific and include as many details as possible. This guide will help you describe the problem in a manner that maximizes the chances of it getting fixed as quickly as possible.
Please add the bug label to any issue that represents a bug.
We love to hear about new uses cases that can make the SDK even more useful.
Suggesting an enhancement works similarly to reporting a bug in the sense that we use the same
issues tracker for it.
Please add the enhancement label to any issue that represents an enhancement.
When suggesting an enhancement, make sure to explain the use case you’re trying to solve. You may suggest a possible solution or even implementation, but first and foremost you should focus on the problem. People more familiar with the inner workings of the SDK may see other ways of solving the same problem.
Having clear and concise documentation makes it easier to use the SDK. We have different types of documentation:
-
The lab project explains the important concepts that you need to know in order to work with InfoArchive and the SDK. It is a separate project in GitHub, so we won’t discuss it further here.
-
The Wiki has a few pages on important topics. This type of documentation focuses on specific tasks that can be accomplished with the SDK. If you’d like to contribute to the wiki, use the
Clone this wiki locallybutton and follow the process for contributing source code as explained below. This documentation assumes you are familiar with the main archiving concepts. -
The JavaDoc is embedded in the source code. Updating or adding JavaDoc thus follows the same process as changing the code, as described in the next section. JavaDoc focuses on low-level details for a particular class or method. It assumes you are familiar with archiving concepts and know what task to perform on a high level.
All source code contributions must come in the form of Pull Requests (PRs). If you submit code in a PR, we assume you have all the legal aspects covered and are authorized by your organization to transfer ownership of the intellectual property to us. GitHub will ask you to sign our Contributor License Agreement (CLA) when you submit a PR to verify this. PRs without a signed CLA will not be merged.
Before you make any changes, you should familiarize yourself with the current source code. The code is split into sub-projects, each of which is built into its own separate jar file:
Each sub-project has more information.
-
You’ll need a recent build of Java 8.
-
You can generate project files for the Eclipse and IntelliJ IDEs by running
gradlew eclipseorgradlew idea, respectively.
At a minimum the build must pass, which you can verify by running gradlew from the root of the project. When you
submit a PR, this build is run on Travis CI
automatically.
PRs with failing checks will not be merged.
The build runs several checks:
-
The source code must follow our style guide. This is enforced by tools like CheckStyle and PMD. The rules for these tools are located in
config/checkstyle.xmlandconfig/pmd.xml, respectively. If at all possible, you should set up your IDE to run at least CheckStyle with our rules. -
All the tests must pass.
-
The tests must cover enough code. The rules for what is "enough" are in
coverage.gradle. On top of that, every bug fix requires a test and so does at least the happy path of an enhancement.
When the build runs on Travis, it also uses sonarcloud to run additional code checks. These will not fail the build, but we make it a habit of keeping things clean. To ensure this, a manual code review will be performed and you may be asked to make changes before we accept your contribution. We may also accept your contribution and make changes after the fact if we think that will improve the code in some way.
It’s important to make the minimal number of changes to support your fix or enhancement so that diffs are small and can
easily be reviewed. In particular, you should make sure that you’ve
configured Git properly with regard to line endings and
that you don’t change the formatting. If you’re using Eclipse, you can import the config/eclipse/formatting.xml
file to ensure it formats source code appropriately.
Public types and members of public interfaces should have JavaDoc comments. Other than that, comments should only be used to explain why something was done a certain way. The code itself should be so clear that comments are not needed to understand what it is doing. Good names help with that a lot.