Contributor’s guide

Welcome to Stackable, we’re happy to have your contributions! Contributions can come in many different ways, and this document is the entry point to point you into the right direction to get your contribution posted as soon as possible.

First of all, if you have a question and something is unclear and you couldn’t find the information you needed, ask a question on GitHub discussions. This is the first place you should go to if you don’t know where to start.
If you found a bug or a feature request and you already know where it would need to go, search for similar issues first! If you cannot find anything, create an issue in the repository that belongs to the component where you found the bug or have the feature request. You can also have a look at the Project overview to find out which repository might be the right place to go to. An issue is also the right tool if you have a suggestion for a fix for a bug but first want to report the bug to raise awareness. 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 easier to submit high-quality issues.
If you are already familiar with the Project overview and you have a particular fix or feature to contribute in code, you can create a pull request in the specific repository. Again, it is useful to first to a quick search if there is already an issue or other pull request that is similar to yours. If that is the case, consider contributing to the existing issue by either adding new feedback or code. The steps to contribute a pull request are outlined below, and you should also consult the Contributing code guidelines to make sure your contribution isn’t missing anything and follow the General pull request guidelines below.
If you want to contribute documentation, follow the Contributing to documentation guideline, as well as the General pull request guidelines below.

Project overview

Please see the Project overview page to get an overview of the most important Git repositories in the Stackable organization.

General pull request guidelines

All our development is done on GitHub and contributions should be made through creating pull requests, follow the GitHub instructions on how to do this. If you are an external contributor, you will need to fork the repository where you want your change to be made.

Signed commits

As a supply chain security policy, all commits and tags in Stackable repositories need to be signed. Signed commits ensure authenticity by verifying that a commit has indeed been made by a certain person and integrity to make sure that no data has been changed after the fact.

Read Notes on Signed Commits with Git and Github for more information on using signed commits.

Instructions

Please make sure that you base your pull request on the latest changes in the main branch of the repository if it is a general change you want to see added to the platform, or off of a specific release branch (named release-23.11 for example) if you want to contribute a fix that is specific to a release. At Stackable we use a branch structure based on trunk based development.

Review preparation

In your pull request, give a comprehensive description of the changes you are making and why, and reference any issues that are relevant to your pull request.

Some repositories have review checklists that are found in the pull request template, for example the operator repositories have these checklists. Before requesting a review, make sure to go through the list and ensure that everything is ready for review.

Some repositories also have automated checks in place that check code style and general consistency. Make sure that all checks are running successfully on your pull request. If you follow the Contributing code guide, a lot of checks should already be covered by your development environment setup (this includes things like linters and formatting).

Once you are ready for review, request a review from 'stackabletech/developers'. If you are an internal contributor, assign yourself to your pull request.

Review

During the review phase, a Stackable employee will review your contribution. Respond to questions and feedback, and improve your submission if necessary.

A single approval of your contribution is sufficient for it to be merged. After your pull request is approved, it can be merged. Internal contributors merge them on their own, pull requests from external contributors are merged by the approver.

Once your pull request is merged, you have successfully contributed! Congratulations!