Contribution guide

antora.yml

@@ -4,3 +4,4 @@ title: Stackable Documentation
 nav:
   - modules/ROOT/nav.adoc
   - modules/internal/nav.adoc
+  - modules/contributor/nav.adoc

modules/ROOT/pages/release_guide.adoc

@@ -0,0 +1,36 @@
+
+
+(this is work in progress that is why it's not explicitely linked in nav.doc)
+
+Prerequisites:
+
+- no branch refs in Cargo.toml
+- (integration) tests are successful
+- the changelog has useful entries
+
+Release:
+
+(from main)
+
+    git sw -c release-0.6.0
+    vi CHANGELOG.md
+    cargo-version.py --release
+    cargo update --workspace
+    make regenerate-charts
+    git commit -am "Release 0.6.0"
+    git tag -a 0.6.0 -m "Release 0.6.0" HEAD
+
+    git push -u --all origin release-0.6.0
+
+Bump dev version:
+
+(from main immediately after a release)
+
+    git sw -c bump-version
+    cargo-version.py --next minor
+    cargo update --workspace
+    make regenerate-charts
+    git commit -am 'Bump next development version'
+
+    git push -u origin bump-version
+

modules/contributor/nav.adoc

@@ -0,0 +1,4 @@
+* Contributor's Guide
+
+** xref:contribution_guide.adoc[]
+** xref:new_product_version.adoc[]

modules/contributor/pages/contribution_guide.adoc

@@ -0,0 +1,96 @@
+= Overview
+
+== Introduction
+
+Welcome to Stackable!
+
+This document will show you the steps needed to contribute to the Stackable Platform. Contributions can come in many shapes and forms but in this document we'll focus on code and documentation improvements. We'll assume you already know what the Stackable Platform is and have a specific issue that you want solved.
+
+This document aims at getting your contribution posted as soon as possible.
+
+== Contribution Workflow
+
+The development of the Stackable Platform takes place on https://github.com/stackabletech[GitHub]. On GitHub, each repository has it's own Issue-Tracker and since Stackable is a platform, there are several repositories where issues and pull-requests can be made. If you already have a good ideea where the issue or pull-request belongs, then you can skip reading to the contribution steps below. Otherwise you might want to a have a look at the <<Repo Walkthrough>> section below for hints.
+
+
+Contribution steps:
+
+1. Lookup if an existing issue already covers your problem
+2. Submit a new issue and/or pull-request
+3. Respond to questions or feedback
+4. Improve your submission if necessary
+5. Closing your contribution
+
+Before submitting a new issue or pull-request, it's always a good idea to check if the issue has already been discussed in the passt and if there is a resolution for it. If that is the case, consider contributing to the existing issue by either adding new feedback or code.
+
+When creating a new issue please provide as much information as you consider relevant. Issues can be bug reports, feature requests and so on. The Stackable repositories provide templates to make it easyer to submit high-quality issues.  
+
+When submitting a pull-request, you might be interested in knowing about the necessary <<Development Environment>>.
+
+== Repo Walkthrough
+
+This is quick walk through the most important repositories:
+
+=== Repository: https://github.com/stackabletech/issues[issues]
+
+This repository exists solely for the purpose of tracking issues related to the Stackable Platform in general. Large topics that impact many or even all of the plattform components are discussed here. There is no code in this repository.
+
+=== Repository: https://github.com/stackabletech/documentation[documentation]
+
+Platform wide documentation, such as this page, are hosted here. Also this repository has references to documentation that is hosted in individual <<Operator Repositories>>. It is the main source from which the public https://docs.stackable.tech/[Documentation] page is generated.
+
+=== Repository: https://github.com/stackabletech/docker-images[docker-images]
+
+The Stackable Platform can be used to install and run up several open-source products such as https://kafka.apache.org[Apache Kafka] or https://trino.io[Trino]. Container images of these products hosted on the https://repo.stackable.tech/[Stackable Repository Manager] and the sources hosted in this repository.
+
+NOTE: Operators host their `Dockerfile`s in their own repository. 
+
+=== Repository: https://github.com/stackabletech/integration-tests[integration-tests]
+
+The Stackable Operators are tested in many environments and across cloud providers. Integration tests are currently driven by `Kuttl` and are hosted here.
+
+=== Repository: https://github.com/stackabletech/t2[t2]
+
+Integration testing across different versions and cloud providers is being developed here.
+
+=== Operator Repositories
+
+At the core of the Stackable Platform are Kubernetes operators used to install and manage various data products. Each operator has it's own repository and therefore it's own Issue Tracker and build pipeline. Every operator repository contains:
+
+* The operator's source code
+* One or more Custom Resource Definitions owned by the operator
+* `Helm` chart to easily install the operator
+* Documentation
+* `Dockerfile` and related artifacts to generate the operator image
+
+== Development Environment
+
+In order to contribute source code, you need an environment that is capable of running the following tools:
+
+* https://www.docker.com/[Docker]
+* https://kind.sigs.k8s.io/[Kind]
+* https://helm.sh/[Helm]
+* https://kuttl.dev/[Kuttl]
+* https://www.rust-lang.org/[Rust]
+* https://www.python.org/[Python]
+
+The documentation is written in https://asciidoctor.org[AsciiDoc] format and processed with https://antora.org[Antora]
+
+Almost all build scripts assume a Unix based environment (preferably Linux).
+
+=== IDEs and Editors
+
+Of course you are free to use whatever works for you best. No editor is perfect but we have positive experience with:
+
+* https://www.jetbrains.com/idea/[IntelliJ Idea] with the `Rust` plug-in
+* https://code.visualstudio.com/[VisualStudio Code] with the `rust-analyzer` extension
+
+For `VisualStudio Code` we also recommend the following extensions:
+* Better Toml
+* CodeLLDB (for debugging)
+* Error Lens (inline error messages)
+* AsciiDoc
+* GitHub Pull requests and Issues
+* GitLens
+* Python
+* Docker

modules/contributor/pages/new_product_version.adoc

@@ -0,0 +1,25 @@
+= New Product Version
+
+== Checklist: adding a new supported product version
+
+This page contains information on the steps that need to be taken when adding a new supported product version to our platform.
+
+One or more new issues need to be created for each new version we want to support.
+
+NOTE: _Support_ is meant in the _technical_ term here.
+This does not necessarily mean that we're going to provide enterprise support for this version to our customers.
+
+In general these are the steps that need to be taken even though some of them are optional depending on what exactly needs to be done:
+
+* Open a _tracking_ issue in the relevant operator repository
+** This issue serves as the hub for all other issues that might have to be opened
+** This issue should contain information like links to changelogs or release notes, it should also contain information on breaking changes and how they affect our operator etc.
+
+* Provide an updated Docker image
+** Open a separate issue in the https://github.com/stackabletech/docker-images/[Docker Images] repository
+
+* Optional: Update the documentation include the newly supported version
+
+* Optional: Update the integration tests to use the new version
+
+* Optional: Update examples to use the new versions