Development

How to start DigiDoc4j development

Since release 1.0.6 the building system for DigiDoc4j is Maven.

git clone https://github.com/open-eid/digidoc4j.git

cd digidoc4j
./mvnw clean package

API is available via JavaDoc.

To run tests:

./mvnw test

To build and run tests inside IDEA

There are no special concerns for building and running tests under IDEA when using Maven.

Finally setup CheckStyle rules like so:

1. Open CheckStyle tool window
2. Change rules to: RIA (define and activate ruleset with checkstyle.xml)
3. Now press run and check that CheckStyle did not find any problems

Releasing in GitHub

1. Update the release notes
2. Update the project.version number in the pom.xml file
3. Add a tag to the last commit (public-*) you want to release
4. Make sure your JAVA_HOME environment variable points to Java 8 JDK installation
5. Run ./mvnw clean package -P delivery to build the artifacts to the target directory
6. Push the changes
7. Draft a new release in GitHub
8. Choose the correct tag for the release, write something useful and upload the built artifacts as assets of the current release
9. Publish the release

Publishing Javadoc to GitHub Pages

Javadoc for DigiDoc4j is available in GitHub Pages. In order to update it, follow these instructions:

1. Make sure your JAVA_HOME environment variable points to the latest Java LTS JDK installation (currently Java 21). As each Java version generates a bit different Javadoc, we don't want any unnecessary "version hopping", which would introduce excessive changes. Java 8 and older versions would generate broken Javadoc for this project.
2. In DigiDoc4j's Git root directory, run the following commands to update Javadoc in gh-pages branch:

   git checkout master
   # Build the project and documentation
   ./mvnw clean package -Dgpg.skip -DskipTests
   git checkout gh-pages
   # Back up the generated Javadoc before emptying the directory (destination does not matter
   # - just make sure to use the same directory for restoring the backup later)
   mv digidoc4j/target/reports/apidocs ../
   # Delete all the files and directories from Git repository except the hidden ones
   rm -rf *
   # Restore the previously backed up Javadoc
   mv ../apidocs/* ./
   rmdir ../apidocs

3. Check Git diff to ensure the modifications are correct
4. Create a new Git feature branch, commit the modifications and create a pull request into gh-pages branch

Releasing in Maven Central Repository

1. Make sure that you have account for Sonatype OSSRH (OSS Repository Hosting)
   • If not, then
     • read http://central.sonatype.org/pages/ossrh-guide.html
     • create Jira account - the same account is used to access Nexus Repository Manager
     • create Jira ticket and ask for permissions to upload artifacts
2. Make sure that you have GPG installed and keys generated
3. Make sure that your public key is published in MIT PGP Public Key Server (it is one option)
4. For deployment there are two possibilities:
   • Create and upload release bundle OR
   • Make sure your JAVA_HOME environment variable points to Java 8 JDK installation and run ./mvnw clean deploy -P delivery -P ossrh with ossrh profile defined in your .m2/settings.xml; usually the structure of settings.xml is following:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>your_user_name</username>
      <password>your_password_for_ossrh</password>
    </server>
  </servers>
  <profiles>
    <profile>
      <id>ossrh</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.executable>gpg</gpg.executable>
        <gpg.passphrase>your_gpg_password</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
</settings>