Releasing your own plugin

After you created an plugin that works with the latest released version of GroIMP, you can publish this plugin to the GroIMP plugin manger. This tutorial assumes you use a gitlab repository, yet this is not required for a GroIMP plugin(see below ).

To understand the following steps lets have a look at the plugin infrastructure and the pipeline and what is suppose to happen after a new version (tag) of a plugin is pushed to gitlab.

The infrastructure inside each plugin repository (that has at least one released version) consists of four main components:

1. The code it self(in git)
2. The package registry (e.g. https://gitlab.com/grogra/groimp-plugins/QSM/-/packages) where the jars and poms of all already released versions are stored. This registry is used for the plugin manager to download the jars and for maven to provide the packages compilation.
3. A gitlab page with the compiled embedded documentation (e.g. grogra.gitlab.io/groimp-plugins/QSM/) this is manly used for the manual web explorer(https://gitlab.com/grogra/groimp-utils/manual-web-explorer) to create https://manual.grogra.de/. This is done so the embedded documentation can be found via search engine or AI bot. Don't be surprise about the question marks on the gitlab page that is only happening there and not on the real website.
4. The plugin.json file (e.g. https://grogra.gitlab.io/groimp-plugins/QSM/plugin.json) This file holds all necessary download links for each version of the plugin and their required libraries. As you can see the download link refers to the package registry.

Except for the code all this is automatically generated using a ci/cd pipeline that compiles the plugin using maven and extracts the information for the different files. The most tricky part is that the latest version of the plugin.json file only exists on the gitlab page. Therefore it is downloaded from the page extended with a new version and uploaded again every time a new version is created. This becomes relevant if the file needs to be altered (see trouble shoot).

This plugin.json already provides all that is needed to install a plugin using the plugin manager. Therefore it would be required to add the link to this file as a repository see here.

Yet to make it easier for everybody it is possible to bundle different plugins.json files to one large file providing a collection of possible plugins. further described here

The GroIMP developer team provides one official collection which is added to the plugin manager by default. This collection is managed in the Plugin web explorer (https://gitlab.com/grogra/groimp-utils/plugin_web_explorer).

The plugin web explorer runs a script once a day that takes all plugin.json files form the plugin_repo.list and turns them into one large file. Further the pipline creates the page plugin explorer https://grogra.gitlab.io/groimp-utils/plugin_web_explorer which is once a day mirrored to plugins.grogra.de Further all jars from the plugins and their libraries are published on plugins.grogra.de and updated once a day (see here).

If you want your plugin added to this list please reach out to us or add an request to the plugin web explorer repository.

The following steps require a Gitlab repository that follows the shape of our template. The code in this plugin must be compilable with the latest released version of GroIMP. Please also test that the documentation you provide compiles properly (see compile_with_help_panels and markdown_syntax_groimp_flavored_markdown).

Further more make sure you have added the right information to your plugin.json file.

Assuming you want to release the very first version of your plugin eg. 0.1, you first have to make sure that this version is also set in the pom.xml (as <version>0.1</version> example) and in the plugin.xml file ( example).

If this is all pushed to the repository you can create the new tag. You can do this on the web view in the left menu on Code > Tags.

In the new window on the upper right corner you can create a new tag with the name “0_1” and a summary of what this version does.

After creating the tag Gitlab automatically starts the pipeline to compile the java package. You can observe whats happening if you got on Build > Jobs in the right menu and select the currently running job.

Assuming this went well and the job succeeded there is one last step you have to do: Go on the left menu on Deployment > Pages and select the tab Domain & settings and make sure “Use unique domain” is disabled. This moves the released pages (with the documentation and the plugin.json) to a consistent URL that does not change with future releases.

This URL extended by “/plugin.json” gives you your plugin.json file this can now be added to GroIMP or to the plugin web explorer.

The steps for additional releases are a simpler, you only have to set the versions right in the pom.xml and the plugin.xml file and create a new tag.

If you provide a download link to your jar and a plugin.json that refers to it you can host this where ever you want.

If you want to change parts of the plugin.json file e.g. the descrption or the help url, or if you want to remove a version, you have to do the following steps:

1. Download the plugin.json manually ( form the gitlab page! not from the repository)
2. Use the downloaded plugin.json to replace the one in your repo.
3. Do do the changes you need to do (make sure it is still a valid json file)
4. Delete the Gitlab page ( on the website left menu > Deploy > Pages, and then delete page).
5. Wait a moment, Gitlab sometimes needs some time to really delete the page.
6. Rerun the pipeline with a version that is not included in the plugin.json

The pipeline always tries to download the plugin.json form the gitlab page but since the page is deleted the pipeline uses the plugin.json file from your repo.

Sometimes things go wrong and you want to get rid of a version of your plugin that is already released.

Todo so you need to:

1. Remove the tag (Left menu: Code > tags and than the little bin next to the version)
2. Delete the package (Left menu: Deploy > package registry and the tree dots next to the packages you want to delete).
3. remove the version form the plugin.json (see above).