Development process

This repository contains scripts that help to manage and develop Knot.x project and its GitHub repositories. Below you will find instructions on how to setup local Knot.x developer's e environment and build:

• Knot.x Stack - a way of distributing a fully functional bootstrap project for Knot.x-based solutions.
• Knot.x Docker Image - which is a base image for Knot.x solutions using the Docker FROM directive.
• Knot.x Starter-Kit - a template project that you can use when creating Knot.x extensions.

Prerequisites

Before proceeding make sure you have installed:

• Java 11
• Gradle 7+
• (optionally) Your favourite IDE - we will use IntelliJ for the purpose of these instructions
• (optionally) Docker installed (if you intend to build Knot.x Docker images)

If you are a Windows user, please install and configure Windows Subsystem for Linux (WSL). Scripts in that repository are designed to be used on Linux-based platforms.

Setup developer environment

Start with cloning this repository into your workspace. Let's call it $KNOTX.

Clone all Knot.x repositories

From the $KNOTX/knotx-aggregator/development directory run:

./pull-all.sh -r ../../ -b master

This will pull all Knot.x repositories into $KNOTX root and checkout default master branch. The -r option specifies the directory where all Knot.x repositories are cloned (which is $KNOTX). Check ./pull-all.sh -h option for help.

Note: Execute all scripts from knotx-aggregator/development directory, executing them from another directory will fail.

Setup IDE

This step is optional

Now as you have all repositories cloned (make sure by running ls -al form $KNOTX) you may setup your IDE. The easiest way to do it is to enter $KNOTX/knotx-stack and run idea .. That will spawn IntelliJ prompt window that will ask you on project import details. After a couple of minutes (importing all modules make take some time) you should end with configured Knot.x project.

Note: knotx-stack repository contains Gradle composite build definition. The repository allows you to re-build all Knot.x modules and use them during integration tests, bypassing the need to publish artifacts to the maven repository first.

Build Stack

From the $KNOTX/knotx-aggregator/development directory run:

./build-stack.sh -r ../../

The -r option points to the directory where all Knot.x repositories were cloned (which is $KNOTX). Check -h option for help.

The build-stack.sh command deploys all Knot.x artifacts to the local Maven repository.

Build Docker Image

To build Knot.x Base Docker image run build-stack.sh with -i (image) flag.

./build-stack.sh -r ../../ -i

After a successful build, you should have knotx/knotx:X.X.X-SNAPSHOT image in your local Docker images repository. Check it running docker images knotx/knotx (note X.X.X-SNAPSHOT should correspond to the current SNAPSHOT version of Knot.x Stack).

Build Starter-Kit

To build Knot.x Starter-Kit run build-stack.sh with -s flag.

./build-stack.sh -r ../../ -s

There are 2 distributions that Knot.x Starter-Kit builds:

• ZIP,
• Docker image.

You can find more details in the Starter Kit repository README. After cloning all Knot.x repositories you can find Starter Kit in the $KNOTX/knotx-starter-kit. Navigate to this repository now and follow the instructions from the Starter Kit repository README to build desired distributions.

Note that you need to build Docker Image if you want to use Docker image distribution. Otherwise, building Stack is sufficient.

Run Knot.x instance using Knot.x Stack

There is a detailed tutorial on how to run Knot.x instance using the Stack:

• http://knotx.io/tutorials/getting-started-with-knotx-stack That base on the released Knot.x version. If you have built the Stack you may use the SNAPSHOT version instead.

Use cases

Note: after cloning the repository please make sure all bash files have proper permissions. If not, please run:

$>git clone [email protected]:Knotx/knotx-aggregator.git
$>chmod -R 755 knotx-aggregator/**/*.sh

Checkout and build all repositories for a specific branch

This option is useful if you are working on a cross-repository feature

From knotx-aggregator/development run:

$>./pull-all.sh -r ../../ -b feature/my-changes -m origin/master
$>./build-stack.sh -r projects/knotx

Pushing cross-repository changes

You may want to use development/push-all.sh script to push changes that touches multiple Knot.x repositories. It requires hub installed. Before you run the script, configure development/update-message.md (see hub docs for details).

From knotx-aggregator/development run:

$>./push-all.sh -r projects/knotx -m "Cross-repo change #123"  -b feature/my-cross-repo-change

where

• projects/knotx is a root folder path for all Knot.x repositories
• "Cross-repo change #123" is a commit message for all changes that will be pushed
• feature/my-cross-repo-change is the branch that will be used to create PR base and will be tracked

Release process

Please refer to the Releasing with Gradle.

CI / CD

Knot.x uses Azure Pipelines to verify commits. Each repository contains an azure-pipelines.yml configuration file that contains details about build and verification steps. Each time there is a change in master repository or some contributor starts the new PR then Azure job starts.

The azure-pipelines.yml file is the same across all repositories. So we use Aggregator to update it in all places. From the repository azure directory execute following commands:

./update.sh

to copy ./azure-pipelines.yml to all repositories, commit and push.