Greetings! We are grateful for your interest in joining the KubeStellar community and making a positive impact. Whether you’re raising issues, enhancing documentation, fixing bugs, or developing new features, your contributions are essential to our success.
To get started, kindly read through this document and familiarize yourself with our code of conduct. If you have any inquiries, please feel free to reach out to us on Slack.
We can’t wait to collaborate with you!
This document describes our policies, procedures and best practices for working on KubeStellar code ia the project and repositories on GitHub. Much of this interaction (issues, pull requests, discussions) is meant to be viewed directly at the KubeStellar repository webpage on GitHub or the parallel pages for KubeFlex and the other components. Other community discussions and questions are available via our slack channel. If you have any inquiries, please feel free to reach out to us on the KubeStellar-dev Slack channel.
Note that the KubeStellar documentation (which drives the website kubestellar.io) is all located in its own repository
Please read the following guidelines if you’re interested in contributing to KubeStellar.
Please make sure that your environment has all the necessary versions as spelled out in the prerequisites section of our user guide
Before reporting a new issue, please search our issue archive (including closed issues) to see if it has already been reported or resolved.
Our complete issue history is publicly available and searchable at our GitHub Issues page, where you can find both current and resolved issues with full discussion threads.
Prioritization for pull requests is given to those that address and resolve existing GitHub issues. Utilize the available issue labels to identify meaningful and relevant issues to work on.
If you believe that there is a need for a fix and no existing issue covers it, feel free to create a new.
As a new contributor, we encourage you to start with issues labeled as good first issue.
We also have a subset of issues we’ve labeled help wanted!
Your assistance in improving documentation is highly valued, regardless of your level of experience with the project.
To claim an issue that you are interested in, assign it to yourself by leaving a comment “/assign”. You may also remove yourself from an issue with “/unassign” in a comment.
KubeStellar uses Prow and GitHub bots to help manage issues and pull requests through slash commands. These commands should be written as comments on their own line:
Issue Management Commands:
/assign @username - Assign an issue to a specific user/unassign @username - Remove assignment from a user/assign - Assign the issue to yourself/unassign - Remove your assignment/good-first-issue - Add the “good first issue” label/help-wanted - Add the “help wanted” labelPull Request Review Commands:
/lgtm - Indicate “looks good to me” (cannot be used on your own PR)/approve - Approve the PR for merging (can be used on your own PR)/hold - Prevent the PR from being merged/unhold - Remove the hold/retest - Re-run failed testsThese commands make it easier for contributors and maintainers to manage the workflow without needing special repository permissions.
We encourage all contributors to adopt best practices in git commit management to facilitate efficient reviews and retrospective analysis. Note: that document was written for projects where some of the contributors are doing merges into the main branch, but in KubeStellar we have GitHub doing that for us. For the kubestellar repository, this is controlled by Prow; for the other repositories in the kubestellar organization we use the GitHub mechanisms directly.
Your git commits should provide ample context for reviewers and future codebase readers.
A recommended format for final commit messages is as follows:
{Short Title}: {Problem this commit is solving and any important contextual information} {issue number if applicable}In conformance with CNCF expectations, we will merge commits that indicate your agreement with the Developer Certificate of Origin. The CNCF defines how to do this, and there are two cases: for developers working for an organization that is a CNCF member, and for contributors acting as individuals. For the latter, assent is indicated by doing a Git “sign-off” on the commit.
See Git Commit Signoff and Signing for more information on how to do that.
View active Pull Requests on GitHub
When submitting a pull request, clear communication is appreciated. This can be achieved by providing the following information:
Following are a few more things to keep in mind when making a pull request.
main branch. Your life will be much easier if the main branch in your fork tracks the main branch in the shared repository.git rebase. It is your friend. It is of your most helpful friends. It is how you can cope when other changes merge while you are in the midst of working on your PR.main into your PR’s branch. That makes a tangled Git history, and we prefer to keep it simple. Instead, rebase your PR’s branch the latest edition of main.gh-pages branch, enabling its use in your fork’s settings) and make the name of your PR’s branch start with “doc-”. If you already have a PR with a different sort of name, you can explicitly invoke the rendering workflow --- unless your branch name has a slash or other exotic character in it; stick to alphanumerics plus dash and dot. You cannot change the name of the branch in a PR, but you can close a PR and open an equivalent using a branch with a good name.We require that the title of each pull request start with a special nickname character (emoji) that classifies the request into of the following categories.
The nickname characters to use for different PRs are as follows
:sparkles:) feature:bug:) bug fix:book:) docs:memo:) proposal:warning:) breaking change:seedling:) other/misc:question:) requires manual review/categorizationNote: The GitHub web interface will assist you with adding the character; while editing the title of your pull request:
Pull requests are subjected to checking by a collection of GitHub Actions workflows and Prow jobs. The infra repo defines the Prow instance used for KubeStellar. The GitHub Actions workflows are found in the .github/workflows directory.
Reviewers will review your PR within a business day. A PR requires both an /lgtm and then an /approve in order to get merged. These are commands to Prow, each appearing alone on a line in a comment of the PR. You may /approve your own PR but you may not /lgtm it. both forms of assent have been given and the other gating checks have passed, the PR will go into the Prow merge queue and eventually be merged. that happens, you will be notified:
Congratulations! Your pull request has been successfully merged! 👏
If you have any questions about contributing, don’t hesitate to reach out to us on the KubeStellar-dev Slack channel.
Our Getting Started guide shows a user how to install a simple “kick the tires” instance of KubeStellar using a helm chart and kind.
To set up and test a development system, please refer to the test/e2e/README.md file in the GitHub repository. After running any of those e2e (end to end) tests you will be left with a running system that can be exercised further.
If you are interested in modifying the Helm chart itself, look at the User Guide page on the Core Helm chart for more information on its many options before you begin, notably on how to specify using a local version of the script.
Prior to making a new release, there needs to be testing that the current Helm chart works with the executable behavior that will appear in the new release.
KubeStellar is Apache 2.0 licensed and we accept contributions via GitHub pull requests.
By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the DCO file for details.