Skip to content

Instantly share code, notes, and snippets.

@tomas-langer

tomas-langer/Examples-repo.md

Last active September 28, 2022 13:07
Show Gist options
  • Save tomas-langer/769deddb836af30bca7fa956adeb3a31 to your computer and use it in GitHub Desktop.
Save tomas-langer/769deddb836af30bca7fa956adeb3a31 to your computer and use it in GitHub Desktop.
Download ZIP
Examples Repository
Raw
Examples-repo.md

helidon-example (probably same as docs layout)

  • reactive (this is what we agreed on with coming of Níma)
    • webserver
    • security
    • oci
  • nima
    • webserver
    • security
  • microprofile
    • server
    • security
      • vault (API)
    • metrics
    • oci
      • atp
      • objectstorage
      • vault (OCI)
    • vault (HCP)
  • kotlin
    • webserver
    • security
    • microprofile

Moving Examples to a separate repository

Helidon Examples should have a separate repository.

How to move from Helidon to Helidon Examples

  1. Create the new repository (probably helidon-examples)
  2. Structure examples the same way Helidon is structured
    1. Mostly followed by current repository, some exceptions exist where MP is used in SE section
  3. Create a PR for each example to the new repository
    1. Use the latest released version of Helidon
    2. Use the same version for the example itself
    3. Fix possible issues with the example (using SE code in MP examples and vice versa, wrong reactive code, best practices for configuration etc.)
    4. Merge into main
  4. Once all examples are merged into the new repository (one-off process, never to be done again)
    1. Remove all existing examples in Helidon repository
    2. Create a develop branch from main branch
    3. Change version in develop to latest snapshot of Helidon
    4. create a branch helidon-2.x from main (if we migrate from 2.x, it would be helidon-3.x if we use 3.x)
    5. Create tag 2.4.x (with the real version number) from helidon-2.x branch (or main, as these should be the same commit)
    6. From here the Development process of Helidon, Release and Release of older version should pick up

Example: We decide to move to examples repo when Helidon 2.4.0 is released, and current master is on 2.4.1-SNAPSHOT.

  • develop branch of examples will use Helidon 2.4.1-SNAPSHOT
  • main branch of examples will use Helidon 2.4.0
  • helidon-2 branch of examples will use Helidon 2.4.0
  • There will be a tag 2.4.0 in Example repository pointing to the same commit as main and helidon-2

Structure is expected to be:

helidon-examples (repository root)
    config
        config-profiles
    microprofile
        tracing
        security
    security
        oidc
        idcs
        basic-uath
    reactive
        basics

Repository

Branches

  • main - Examples against the latest released production version of Helidon (3.x.x)
  • develop - Examples against latest master of Helidon repository (using SNAPSHOT version)
  • develop-v.x - Examples against latest helidon-x of Helidon repository (using SNAPSHOT version)
  • helidon-v.x - Examples against major versions of Helidon

Why do we need develop branches? Each PR in Helidon master needs to be validated. If we used the helidon-x branch, we would need to create a branch for each PR, change all the versions and then run it. If we use develop branch, we do not need to do anything with examples when building them against the snapshot version of Helidon.

Expected branches after version 3.x is released (I do not expect to expose examples for version 1.x anymore):

  1. main - latest release of Helidon (same as helidon-3 until Helidon 4.0.0 comes out)
  2. helidon-2.x - latest release of Helidon 2.x.y
  3. helidon-3.x - latest release of Helidon 3.x.y (same as main)
  4. helidon-4.x - latest release of Helidon 4.x.y (currently ALPHA)
  5. develop-2.x - current last development snapshot version in the 2.x version (such as 2.4.2-SNAPSHOT)
  6. develop-3.x - current last development snapshot version in the 3.x version (such as 3.0.1-SNAPSHOT)
  7. develop-4.x - current last development snapshot version in the 4.x version (4.0.0-SNAPSHOT)

Tags

There will be a tag for each version that is integrated with the Helidon version as the tag name.

Expected tags after version 3.x is released (I do not expect to expose examples for version 1.x anymore):

  1. 2.4.1
  2. 3.0.0

Release

The following steps will be carried out to release the latest version. Let's assume version 3.0.0

  1. Helidon is released
  2. New branch helidon-3.0.0-release is created from develop
  3. develop is moved to the next SNAPSHOT version (3.0.1-SNAPSHOT)
  4. helidon-3.0.0-release is now worked on
    1. Version of all example parents updated to 3.0.0
    2. Tests
    3. Fixes
  5. helidon-3.0.0-release is merged into main (now main contains working examples against 3.0.0)
  6. helidon-3.0.0-release is merged into helidon-3.x (or helidon-3.x is created from it)
  7. helidon-3.0.0-release is deleted
  8. Tag 3.0.0 is created from helidon-3.x

Example: Release of version 3.0.0 when 2.4.1 is the previous version

Before release:

  • develop branch of examples uses Helidon 3.0.0-SNAPSHOT
  • main branch of examples uses Helidon 2.4.1
  • helidon-2.x branch of examples will use Helidon 2.4.1
  • helidon-3.x branch does not exist

After release:

  • develop branch of examples will use Helidon 3.0.1-SNAPSHOT
  • main branch of examples will use Helidon 3.0.0
  • helidon-2.x branch of examples will use Helidon 2.4.1
  • helidon-3.x branch of examples will use Helidon 3.0.0
  • There will be a tag 3.0.0 in Example repository pointing to the same commit as main and helidon-3.x

Release of older version

The following steps will be carried out to release a non-latest version. Let's assume Helidon is now on version 3.0.0 and we need to release 2.7.2

  1. Helidon 2.7.2 is released
  2. New branch helidon-2.7.2-release is created from branch develop-2
  3. develop-2 is moved to next SNAPSHOT version (2.7.3-SNAPSHOT)
  4. helidon-2.7.2-release is now worked on
    1. Version of all example parents and modules updated to 2.7.2
    2. Tests
    3. Fixes
  5. helidon-2.7.2-release is merged into helidon-2 (now helidon-2 contains working examples against 2.7.2)
  6. helidon-2.7.2-release is deleted
  7. Tag 2.7.2 is created from helidon-2

Example: Release of version 2.7.2 when 3.0.0 is the latest version

Before release:

  • develop branch of examples uses Helidon 3.0.1-SNAPSHOT
  • main branch of examples uses Helidon 3.0.0
  • develop-2 branch of examples uses Helidon 2.7.2-SNAPSHOT
  • helidon-2 branch of examples uses Helidon 2.7.1
  • helidon-3 uses Helidon 3.0.0

After release:

  • develop branch of examples is unchanged
  • main branch of examples is unchanged
  • develop-2 branch of examples uses Helidon 2.7.3-SNAPSHOT
  • helidon-2 branch of examples will use Helidon 2.7.2
  • helidon-3 branch of examples is unchanged
  • There will be a tag 2.7.2 in Example repository pointing to the same commit as helidon-2

Development process of Helidon

Developing current major version

We need to validate the develop branch of examples repo against the latest master of Helidon repo.

Not sure what the possibilities are, ideally:

  1. You create a PR against Helidon master, let's assume branch 3201-my-big-change
  2. Validation
    1. Is there a branch 3201-my-big-change with PR against develop?
      1. YES - Use this branch to validate against the PR
      2. NO - validate develop branch against the PR's code (we assume there is no change required in examples)
  3. If validation fails, PR against main repo cannot be merged
  4. If validation succeeds, PR can be merged (and the example PR should be merged as well)

Developing older version

We need to validate the develop-x branch of examples repo against the latest helidon-x of Helidon repo.

  1. You create a PR against Helidon helidon-x branch, let's assume branch 4444-very-important-fix
  2. Validation
    1. Is there a branch 4444-very-important-fix with PR against develop-x?
      1. YES - Use this branch to validate against the PR
      2. NO - validate develop-x branch against the PR's code (we assume there is no change required in examples)
  3. If validation fails, PR against main repo cannot be merged
  4. If validation succeeds, PR can be merged (and the example PR should be merged as well)

User use cases

  1. I am interested in examples against the latest version of Helidon
    1. I go to helidon-examples repository, clone it and use it
       git clone https://github.com/helidon/examples.git
   cd webserver/basics
   mvn package
   java -jar target/webserver-basics.jar
  2. I am interested in examples against a specific major version of Helidon
    1. I go to helidon-examples repository, clone it, switch to branch helidon-x and use it
       git clone -b helidon-2 https://github.com/helidon/examples.git
   cd webserver/basics
   mvn package
   java -jar target/webserver-basics.jar
  3. I am interested in examples against a specific version of Helidon
    1. I go to helidon-examples repository, clone the tag X.Y.Z and use it
       git clone -b 2.3.2 https://github.com/helidon/examples.git
   cd webserver/basics
   mvn package
   java -jar target/webserver-basics.jar
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment