Publishing an Add-on

This guide will help you to set up everything you need for publishing your open-source add-on to the Jmix marketplace.

With our proposed approach both source code and binary artifacts are hosted on GitHub.

Alternatively, you can publish your add-on artifacts to Maven Central. In this case, create a GitHub repository for your source code, set up publishing by yourself and then follow the Register Add-on in Marketplace instructions.

Create Add-on Project

You can create your new Jmix add-on project through the Jmix Studio Project wizard using the Add-On template.

Please don’t use io.jmix.* as a base package and artifact group of your add-on. This name is reserved for Jmix core add-ons. Ideally, the base package should be a reverse-DNS notation of your own internet domain.

To interact well with the GitHub Actions workflows we will see later, you should change the repository settings for publishing add-on artifacts to GitHub Packages:

build.gradle
// ...
publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/" + System.getenv("GITHUB_REPOSITORY"))
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
                password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
    publications {
        javaMaven(MavenPublication) {
            artifactId = archName
            from components.java
        }
    }
}

Additionally, you should remove the version attribute in build.gradle (under group = 'my.new.jmix.addon'). Instead, create a file called gradle.properties with the version information directly next to the build.gradle file:

gradle.properties
version=0.0.1-SNAPSHOT

Create GitHub Repository

Now you need a GitHub repository. GitHub offers all necessary parts for publishing an open-source add-on:

  • source code hosting

  • continuous integration system (GitHub Actions)

  • package management (GitHub Package Registry)

You can create a new GitHub repository here.

Choose License

There are several open-source licenses that you can choose from. Apache License, Version 2.0, as well as MIT License, are common liberal licenses for open-source projects. Jmix itself is licensed under Apache 2.0.

Once you have picked a license, put the license file into the root directory of your GitHub repository.

Set up CI

GitHub offers a built-in CI system, that compiles the code, runs tests, performs releases, etc. for free for open-source projects.

By adding the following GitHub action workflow files into your GitHub repository, the CI system will perform compilation and execution of automated tests. You will need to create the directory .github/workflows manually in the repository.

test.yml
name: CI pipeline

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    name: CI pipeline
    runs-on: ubuntu-latest
    steps:
      - name: Git Checkout
      - uses: actions/checkout@v2

      - name: Set up JDK 17
      - uses: actions/setup-java@v1
        with:
          java-version: '17'

      - name: Run tests
        run: ./gradlew test

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v2
        if: always() # always run even if the previous step fails
        with:
          report_paths: '**/build/test-results/test/TEST-*.xml'
release.yml
name: Publish release
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v1
        with:
          java-version: '17'
      - name: Publish package
        run: gradle -Pversion=${{ github.event.release.tag_name }} build publish
        env:
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_USERNAME: ${{ github.repository_owner }}
          GITHUB_TOKEN: ${{ github.token }}

With those two files in place GitHub Actions will perform the following tasks:

  • compile the code

  • run unit / integration tests

  • store test results

  • publishes a new version for newly created releases

Create Release

GitHub allows creating releases through the Web UI and the CLI. For the web UI, you have to first create a tag for a particular commit. Next, you can create the corresponding release. See GitHub docs for more information.

To create a GitHub release through the CLI use the following command: gh release create 0.1.0. You should replace 0.1.0 with your desired version to create.

We propose to follow semantic versioning, which defines how to increase version numbers based on the type of change you performed in this release. It allows users to more easily understand the potential impact of a version update.

Once the release is created, GitHub actions will create the artifact and release it accordingly.

Register Add-on in Marketplace

Create Issue

To publish an add-on to the Jmix Marketplace, you need to create an issue in the jmix-website-content repository. Select "Publish Add-on to Marketplace" and enter the add-on name and the Github repository it is located in.

After you created the issue, we will check the add-on and, if the add-on artifacts are published on GitHub Packages, create proxies to allow users to download the artifacts from the standard Jmix repositories global.repo.jmix.io and nexus.jmix.io.

Submit Description

Create a PR with the description of your add-on in the add-on directory of the jmix-website-content repository. We accept the PR and publish the content on the website.

If you later want to make changes to your description, you can create another PR with your desired changes in this repository.

Update Jmix BOM

After the release is published on GitHub, you will be able to download the artifact through the Jmix artifact repositories global.repo.jmix.io and nexus.jmix.io.

Generally, Jmix works with BOM (bill of materials) to centrally manage compatible versions. You can find the versions that are specified for a given Jmix release in the jmix-bom project on GitHub.

The main benefit of this approach is that users don’t have to manually find out the correct version of your add-on that is compatible with their version of Jmix. Instead, you declare which version is working correctly with a particular Jmix release centrally in the BOM.

To connect your release with a particular Jmix version, you can create a PR to the corresponding release branch.

  1. Fork the jmix-framework/jmix repository.

  2. Switch to a Jmix release branch you would like to add your release to (like release_2_4).

  3. Add a line with your maven coordinates and the correct version to jmix-bom/bom.gradle:

    api 'my.new.jmix.addon:my-add-on:1.0.0'
api 'my.new.jmix.addon:my-add-on-starter:1.0.0'

  4. Create a PR with the target branch: release_2_4 of the jmix-framework/jmix repository.

When a new major or minor Jmix version is released (for example, 2.5), its BOM doesn’t contain any third-party add-ons because they are not tested for compatibility with the new version. You should submit a new PR for the corresponding release branch (for example, release_2_5) to include your add-on in the new BOM. Until your add-on is not in the BOM, users can still use your add-on with the new Jmix version if they explicitly specify the add-on version in their build scripts.