Skip to main content

Contribute

Please take a second to learn about the initium-platform code repo.

We greatly appreciate bug fixes, documentation improvements and new features, however when contributing a new major feature, it is a good idea to first open an issue, to make sure the feature fits with the goal of the project, so we don't waste your or our time.

How To Contribute​

If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question.

If you don't see your idea listed, and you think it fits into the goals of this project, do one of the following:

  • If your contribution is minor, such as a typo fix, open a pull request.
  • If your contribution is major, such as a new feature, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work.

Conventional Commits​

We use Conventional Commits in this repo. We encourage contributors to name their PRs and commits accordingly. That is required for keeping the repo clean, and for release-please to do its job when automating release creation.

Basically, the fix and feat words on commits will trigger new releases (with fix being patch versions and feat minor versions, unless there is an exclamation mark (!) after one of both, which will trigger a major version release). Other keywords won't trigger releases, but they are welcome in order to better readability of the changes made. Examples: docs, chore, ci, test and so on.

Bug Reports​

A perfect bug report would have the following:

  1. Summary of the issue you are experiencing.
  2. A simple repeatable test case for us to run. Please try to run through it 2-3 times to ensure it is in fact repeatable.

We would like to avoid issues that require follow up questions to identify the bug. Those are difficult to work on unless we have a repeatable test case.

How to create a new release​

PLEASE NOTE: In order to make sure this release pipeline works, every PR and commit MUST use the Conventional Commits syntax.

This project uses an automated release setup that is based on release-please. For a more detailed overview on how it works, feel free to read their official introduction.

In short, what happens is that during the normal lifecycle of contributions, as you keep merging PRs, a new release PR will be created (or updated), which will list the changes that will be included in that release ( for an example, see https://github.com/nearform/initium-platform/pull/11 ).

Once you merge the PR, a new release will be created and the CHANGELOG.md file will be updated as well. As soon as the release is created, this workflow will be run on top of it, and as a result it will upload to the release the final assets that we deliver for the end-user.

These assets can then be found on the release assets section ( for an example, see https://github.com/nearform/initium-platform/releases/tag/v0.0.1 ).

Running the local stack​

Since this project is mostly based on the ArgoCD app of apps concept, it will require a Git repository to host the components that will be deployed by ArgoCD on the cluster.

Usually you would see your ArgoCD Applications pointing to a Git repository that is available to your network. On Initium, we bypass that requirement by providing your local repository ( the one you use once you clone the initium-platform repository in your own workstation ) as a "remote repository" to the eyes of ArgoCD when you deploy the stack locally.

How this is done is simple:

REMEMBER: As ArgoCD will use the latest commit to checkout changes, you will need to commit your changes locally, otherwise ArgoCD won't be able to see them. Pushing is NOT REQUIRED.

This change will allow you to test the entire solution without requiring special access to the remote Git repository. All you will need is just your workstation and an internet connection.

Renovate Bot​

This project makes use of the Renovate Bot to automatically bump chart versions.

Bump your addons using a single PR​

There are some edge cases to be considered when your addon is divided in multiple charts ( for example, see the istio addon ). In such cases, Renovate Bot will by default open a PR for each chart detected to be bumped, although that would make the PR difficult to be merged, as each part of the Istio stack has to be bumped as a whole for it to work correctly.

In order to fix that behavior, you will need to add into the packageRules section an object that will instruct the Renovate bot to consider the addon as a whole. Following the istio example, this is the configuration to be used:

{
  matchPaths: ["addons/istio/**"],
  groupName: "Istio Helm Chart"
}

You can find out more about this syntax on the documentation page at: https://docs.renovatebot.com/configuration-options/#packagerules.

FAQ​

Q: Why does this repo create a Tilt local_resource for Istio ingress since there is already a MetalLB instance setting an Load Balancer IP address for it?

A: As per the Kind docs:

On MacOS and Windows, docker does not expose the docker network to the host. Because of this limitation, containers (including kind nodes) are only reachable from the host via port-forwards, however other containers/pods can reach other things running in docker including loadbalancers.

The Tilt local_resource for port-forwarding the Istio ingress ports is a workaround for that limitation.

Last updated on