Creating components

Introduction

Basically, there are two starting points when creating new components. The first is when you compose an application and figure out that the component repository doesn't offer the business capability you were searching for. In this case you would add a planned component to the application and use the three-dots menu on it to create a service project (click on "Create project"). The planned component's card will now show a link to the new project, so you can access it directly from here.

The second starting point is when you plan to create a new business capability in order to add it to your repository. In this case you would start on the Projects overview page in Solution Designer and use the "Create" button to create a new service project. Please see setting up service projects on how to create new projects.

Depending on the development type you choose you can find additional information. After having implemented the service project according to your requirements and tested everything, the next step is to release the project to the component repository to make it available as a component for applications.

Releasing service projects

IBM Industry Solutions Workbench offers two pipeline definitions for service projects, one is the release pipeline and the other is the deploy pipeline. While the deploy pipeline is used to deploy a single microservice to a deploy target mainly to do testing in a real environment, the release pipeline publishes a service project to the component repository (see build & deploy).

General idea of releasing

In order to use and deploy a service project the helm charts and related docker image(s) has to be released and published.

Releasing also includes dedicated versioning and a release management. So it is ensured, that the correct package of changes are delivered in one released version. IBM Industry Solutions Workbench supports SemVer 2.0 to do so.

And the second part is to publish the versioned release and use the release version for all the artifacts: helm chart and docker image.

Usage in application composite projects

Only released artifacts can be used in the application composite projects. There support not only releases but also pre-releases, hence also work in progress releases can be deployed tested and previewed.

Usage of pre-releases

It is recommended to use several different stages like development, testing and production for example. And only development might use the unstable pre-release version, and the other stages only use stable releases.

In the application composite project is ArgCD used for the deployment of that project. ArgoCD does take per default only releases in account and ignores pre-releases, if expression used like these

1.*
>=2.0.0

If pre-releases have to be taken into account expressions like these has to be used:

1.0.1-alpha
>=2.3.2-0
>=3.0.0-0,<3.0.1-0

Versioning service projects

General idea of versioning

The general idea is to create released artifacts based on the version information on project itself, e.g., the package.json in case of TypeScript or JavaScript service projects or pom.xml in case of Java service project.

So the native way is used to managing the version of that project, hence the native toolchain to maintain and read the version can be used.

Features

The approach support

using the own development and release workflow in manner of versioning
creation pre-release versions using the SemVer v2 postfix -
re-releasing of same version is prevented by default, but can be disabled
developer friendly releasing of pre-releases as per default in this case an increasing number is added to the pre-release version

Limitations

The known limitations are

Only supported Stacks can be supported to determine the release version information
Only SemVer 2.0 is supported due to limitation of helm
- npm uses SemVer 2.0
- maven supports SemVer 1.0 plus an additional set of complex rules. So for example the plus sign is not support in this case

Usage of version

The feature is limited by SemVer 2.0, which is supported and required by Helm/General Conventions/Version Numbers.

The general idea is to distinguish between

pre-releases e.g., 0.0.1-alpha: used for development and intermediate deployments on the related stage(s) for example DEV
releases e.g., 0.0.1: used for tested and approved released versions, and deployments on the related stage(s) for example TEST or PROD

If a version is released. It is not recommended to re-release that version. Hence, if for example 2.0.0 was released once, but a bug was found, the next bugfix version has to be created e.g., 2.0.1, otherwise it is not guaranteed, that the correct states are deploy on all systems.

Precedence of versions

The precedence defined by SemVer:

Precedence refers to how versions are compared to each other when ordered.
Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence).
Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.
Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version:
Example: 1.0.0-alpha < 1.0.0.
Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows:
Identifiers consisting of only digits are compared numerically.
Identifiers with letters or hyphens are compared lexically in ASCII sort order.
Numeric identifiers always have lower precedence than non-numeric identifiers.
A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.
Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

Life-cycle

Preparation:

The project is created and will start automatically with 0.1.0
The "build and release" pipeline has to be created

Daily work:

The planned changes on the project will be applied
- Adjusting model
- Adjusting code
- Adjusting the (pre-)release version (e.g., 0.2.0-alpha)
Either manually or automatically the build & release pipeline will be triggered
Optional: Continue with step 1.
Promotes release by removing the pre-release information e.g., 0.2.0
Either manually (optional) or automatically trigger the build & release pipeline
Define next version and adds pre-release information e.g., 0.3.0-alpha
Continue with step 2.

Documenting a component

Documentation can be created for a component in the form of a readme file, which is then delivered with the component. Create a file named README-COMPONENT.md in the root directory of the cloned project and commit it to the git repository of the service project.

Licensing a component

If you create a file named LICENCE in the root directory of the cloned project and commit it to the git repository of the service project, it will not ship with the component.

Additionally or alternatively, the name and URL of the component can also be specified. This information is taken from your service project.

Licensing a Domain Service Project (TypeScript)

Add the following property to the package.json file:

{ "license" : "SEE LICENSE IN <filename>" }

"licenses" : [
{ "type": "MIT", "url": "https://www.opensource.org/licenses/mit-license.php" }
]

Licensing a Domain Service Project (Java)

Add the following property to the pom.xml file. Only the first one is taken:

<licenses>
  <license>
    <name>Apache License, Version 2.0</name>
    <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
  </license>
</licenses>

Set maintainer of a component

The maintainer of the component must be specified. This information is taken from your service project.

Set maintainer of a component to a Domain Service Project (TypeScript)

Add the following property to the package.json file:

{ "author": "First name Last name <isw@ibm.com> (https://www.ibm.com)" }

{ "name" : "First name Last name", "email" : "isw@ibm.com", "url" : "https://www.ibm.com" }

Set maintainer of a component to a Domain Service Project (Java)

Add the following property to the pom.xml file:

<organization>
  <name>Codehaus Mojo</name>
  <url>http://mojo.codehaus.org</url>
</organization>