Development

Visual Studio Code DevContainer

For Easy development use Visual Studio Code DevContainer, you can find the basement from the Development Containers at nolte/vscode-devcontainers.

Precondition for Use

  • Create you Github Personal Access Token under github.com/settings/tokens with the following scopes:

    • read:packages
  • Login to fetch the required dev containers

    docker login docker.pkg.github.com
  • Grab you a Coffee and wait for 3 Minutes (This happens on the first time use)
  • Click Terminal -> New Terminal and execute the following command:
    make

Process

branch description
master The master will only used for Presentation, and the Deployment process.
tags/v* All Created Releases must be start with a v* prefix at the tag name.
gh-pages Branch for the Static HTML presentation, generated by the GitHub Release Workflow.
develop Branch for the current development, this branch will be used for integrate new Features, and starting the release flow.
feature/* This are temporary branches for develop new functions.
fix/* Used for bugfixing from existing versions, if no FastForward Fix Possible.

Please use the develop branch for new features and fixes.

Releasing

The Github Release Assets will be automatic attach from the build job see .github/workflows/gorelease.yaml. The Release Process use goreleaser for create the the Binaries. Each Release will be start, at the moment, from the develop branch. The release description will be generated by release-drafter/release-drafter in a seperated workflow. Look to .github/workflows/release-drafter.yml for the Job, and .github/release-drafter.yml for the description configuration.

Build

The Build scripted at the moment splitted into the GitHub Workflow Stuff and a combination of Makefiles and Shell Scripts, an Targets from the nolte/plumbing. The Makefile/Magefile should be use for the local development, permanten using the full GitHub Workflows needs a lot of time.

You will get the compleat list of possible Magefile Targets with:

cd ./tools && go run mage.go -l

CI/CD

For local usage the GitHub Actions we use the nektos/act Project. The first local execute will be take some time for pulling the large nektos/act-environments-ubuntu:18.04 image.

Workflow Job Job Local Description
Classic CI/CD build 👍 This is the Classic Build job with Static Tests, and compile the provider.
Release Flow releaseBuild 👎 This Job are used for attatch Release Assets to a existing GHRelease
Acception Tests CI/CD acc 👎 Starting a full run of Terraform Integration Tests, with starting a local kind cluster and deploy a v2 Harbor.
shellcheck shellcheck-check 👍 Check the Schell scripts for problems.
devcontainers devcontainers-check,docscontainers-check 👎 Simple build job for the both Dev Containers (VSCode and mkdocs)
# call job
act -j <job> -P ubuntu-latest=nektos/act-environments-ubuntu:18.04

# example calling the build workflow
act -j build -P ubuntu-latest=nektos/act-environments-ubuntu:18.04

Since the Acception Tests Workflow is a matrix build, for better Tests again different Harbor Versions. It is not possible to run it locally, because the you can`t start two or more Kind Cluster out of the box locally. Feature Request #114 for call a specific Matrix Workflow.

HarborAPI Client

At the moment the Swagger Json for generate the Api Client, look ./docs/adr/0001-use-swagger-for-generate-http-client.md.

For manipulate the Swagger Json, and generating a useable go api client, we use evanphx/json-patch inside the buildprocess, for adding or replace different JSonStructures. So if you need new manipulations, change the scripts/swagger-specs/patch.1.json patch file. More informations about jsonpatch. The problem are tracked, #12474.

Docs

The Documentation are presented in Different Formats, as GitHub Page , and for the registry.terraform.io.

GitHub Page

If you use the VSCode DevContainer, the mkdocs container will be started automatical, as a sidecar container. At the Development you ca access the current state from the Documentation at 127.0.0.1:8000. For some extras, like Tasks List or Snippeds we use the MarkdownPP project.

Terraform Registry

The Focus from the Registy Documentation is the Provider self, for example Resources and Datasources. More informations about the Required Format at terraform.io.

Development Shortcuts

build and test in one command

make compile \
    && make install \
    && bats scripts/test/bats/build
terraform import -var harbor_endpoint=${HARBOR_ENDPOINT} -var harbor_base_path='/api' harbor_project.main 24