Components Publication

Workflow to publish open source components

Components Publication

Regular Git Repository Update

  1. Push the changes to the GitHub repository Open Source Components.

    1. Verify that the build job in the CI pipeline was successful.

  2. Push the changes to the GitHub repository. The statistics for developer activities will be automatically updated.

Continuous Delivery Pipelines

See Readme.

Maven Central Publication

The following process is used to publish tangly open source component on Maven Central.

  1. Publish artifacts of a component with the script uploadToMavenCentral.sh. Do not use the gradle task gradle publishAllPublicationsToMavenRepository -Pmode=prod. Sonatype cannot handle a parallel upload of multiple components and simply close the connections during upload (Status 2020-Q2).

    1. Pre-activity: test publishing with gradle publishToMavenLocal

    2. Pre-activity: check on bitbucket the product compiles through the CI continuous integration pipeline

    3. Post-activity: tag repository on git to identify the version of the published packages. The tag version semantic part must be the same as the package version on Maven Central The tag is of the form -AcronymComponent-MajorVersion-MinorVersion-PatchVersion-

    4. Verify with git tag label and git push origin --tags

  2. Log into Sonatype Maven Central Repository

    1. Go to Staging Repositories

    2. Find your temporary repository at the end of the list

    3. Review the content of the repository

    4. Close the repository-button on tool list-

    5. Close stage is initiated and checks are performed. If everything was fine, the content was published.

    6. Release the artifact-button on the tool list-

  3. See Static Website Publication to update the website

It takes up to one day until the component is visible in Maven Central website upon publication.

On the positive side, the last publications were performed in less than 30 minutes.

Below the dependencies between tangly open source components as defined in the multi-modules Gradle Build Tool build file.

nettanglyerpbddcommonscoredevfsmgleamuicollaboratorscrminvoicesledgerproductsui

Decisions

  1. The open source components are stored in a mono repository. Each component is declared as a gradle module.

  2. We use de facto standard Git.

  3. We are hosted at GitHub [1]. Mirror repositories are hosted at GitLab, Bitbucket, and the technical university of Lucerne.

  4. The continuous delivery pipelines work for the primary and all mirror platforms. The build uses the eclipse-temurin Java distribution. This docker image is based on Ubuntu. The installation of additional packages is therefore simplified [2].

The synchronization is performed with the command

git push --prune
      https://github.com/marcelbaumann/tangly-os.git
      +refs/remotes/origin/*:refs/heads/* +refs/tags/*:refs/tags/*        (1)

git remote                                                                (2)

git push origin-github                                                    (3)
git push origin-gitlab
git push origin-hslu
git push origin-bitbucket
1 Push the repository with all remotes, references and tags to GitHub specified repository
2 List all remotes associated with this git repository
3 Push the master branch to the origin-github remote repository. The push shall trigger the continuous integration pipeline

You must create a token for developer account to be able to push changes and trigger the CI pipeline. The username is your account username The password is the generated token [3]. Store it in a safe place.

Findings

  1. We needed to manually publish the public key on keys.openpgp.org

  2. Gradle build file has a condition including disabling the signing plugin on the CI pipeline because keys and associated authentication are not available. I decided not to upload private keys to bitbucket. See the documentation at the beginning of the Gradle build file for details.

Set the property if you want to sign the component artifacts and publish to Maven Central.

Static Website Publication

Introduction

The static website uses Asciidoc to write all documents.

The static website uses Hugo as site generator. The Hugo theme is Docsy.

Configure Asciidoctor

The new version of the Hugo support configuration of Asciidoctor through config.toml therefore no manipulation of asciidoctor is needed. As a bonus, the files generated by PlantUml are created in the correct folder. We still need to install the referenced packages.

sudo gem install asciidoctor-diagram (1)
sudo gem install asciidoctor-bibtex (2)
sudo gem install asciimath (3)
1 Provides support for all diagrams such as plantUML and mermaid.
2 Provides support for formal bibliography references.
3 Provides support for mathematical and logical expressions in documents.

Docsy Tailoring

The docsy theme is missing some features. It does not support asciidoc styling or commenting blogs. Our extensions follow the official rules how a theme can be tailored and expended.

The major changes are:

  • Inclusion of the styling sheet asciidoctor.scss to style asciidoc documents [4].

  • Inclusion of the shortcodes extension shortcodes.html layouts and the style file shortcodes.scss to support file attachments in the website [5].

  • Extension of the blog section with comments-uttereances.html to support comments on blog articles [6].

  • Changes in the header and footer partials to display mathematical expressions and well-styled copyright [7].

All changes are defined in the assets and layouts folders as part of our website content. Hugo’s algorithms select local overwritten files and ignore the corresponding theme files.\

The current structure of our extensions follows the official approach how a Hugo module should be extended. We do not change any files in the theme. All changes are defined locally. We use the selection algorithm of Hugo to activate our tailoring and extensions.

Create Website

The tangly open source components website is hosted under Documentation.

Read the instructions in the asciidoctor script file under the scripts' folder. Four scripts are provided to generate the Hugo static site with associated structure and theme.

  1. the script initiateHugo.sh creates the layout of the site and retrieves the theme.

  2. the script populateHugo.sh populates the site with our content.

Upon completion of local development, you must start a local Hugo server and generate the indexing files for lunr search. Before uploading the site, stop the Hugo local server.

  1. the script completeHugo.sh generates the static pictures and copies them to the static folder and publish the whole site on bitbucket.

Upon completion, the site is published on the web for all.

Set JDK Version under macOS

Install regular Java JDK such as the Oracle or OpenJDK distribution. They will be located under /Library/Java/JavaVirtualMachines.

If using bash or zsh shell, add the following commands to your .bash_profile or .zshrc [8].

alias java17 = "export JAVA_HOME=`/usr/libexec/java_home -v 17`; java -version"
alias java19 = "export JAVA_HOME=`/usr/libexec/java_home -v 19`; java -version"
alias java20 = "export JAVA_HOME=`/usr/libexec/java_home -v 20`; java -version"
alias java21 = "export JAVA_HOME=`/usr/libexec/java_home -v 21`; java -version"

You can set the exact version such as 17.0.1 to precisely select a JDK or set an overall version such as 17 to select a generic version.

After restarting your terminal, the command java17 will set JDK 17 to default JDK (if installed on your macOS).

The list of JDK can be found with

/usr/libexec/java_home -V

Create Docker Distribution

Generate the ERP application as a production release.

gradle install -DproductionMode=true (1)
gradle install -Pproduction
unzip ./build/distributions/net.tangly.erp.ui-<version>.zip (2)
docker build -t erp-docker . (3)
docker run -ti -p 8080:8080 erp-docker (4)
1 Generates a production distribution stored under ./build/distributions
2 Unzip the packed distribution because the docker base image does not contain unzip utility
3 Build the docker image named erp-docker
4 Run the docker image erp-docker and map the image port to 8080
1. We moved from Bitbucket to GitHub in 2022. The reasons were that the new platform supports publishing of static website with a lot more functionalities. The new agile project management functionality with Scrum boards, sprint iterations and insights report is very interesting.
2. It is a shame that each hosting platform has created their own incompatible pipeline script syntax.
3. This is necessary if you have enabled two factors authentication. The other approach is to generate an SSH key and perform all operations other SSH.
4. I asked for a change request on GitHub for Docsy to better support asciidoc documents. The Docsy team decided that their priorities are different and rejected the request.
5. This change is defined as a merge request. The pull request is quite old and seems to have a low priority.
6. The current setup of the template does not allow selection of a comment solution per configuration.
7. An issue report exists on GitHub about the copyright issue.
8. zsh is the default shell in current macOS versions.