We’d love to accept your patches and contributions to this project. Please review the following guidelines you'll need to follow in order to make a contribution.
If you are interested in going beyond a single PR, take a look at our Contribution Ladder and learn how to become a reviewer.
We prefer communicating asynchronously through GitHub issues. We also have a Slack channel in the CloudFoundry workspace.
We suggest beginning by submitting an issue so any high level feedback can be addressed early, particularly if significant effort will be involved.
Please submit feature requests and bug reports by using GitHub issues and filling in the supplied template with as much detail as you can.
Before submitting an issue, please search through open ones to ensure others have not submitted something similar. If a similar issue exists, please add any additional information as a comment.
Pull requests are welcome for all changes, whether they are improving documentation, fixing a bug, adding or enhancing a feature, or fixing a typo.
Changes to the behavior of korifi/api or korifi/controllers will require that you build and test your changes.
When adding new functionality or fixing bugs, add appropriate test coverage where possible. Different parts of the code base have different strategies and patterns for testing, some of which may be in flux at any point in time. Consider commenting on the issue to seek input or opening a draft pull request to seek feedback on approaches to testing a particular change.
When contributing new diagrams to the docs, provide a way for others to update the diagrams in the future. We recommend using Draw IO since it supports embedding diagram metadata within the PNG files themselves. This allows future contributors to import the diagram and update it.
To build the project from source, please consider the docs on local development.
- Commit messages should include a short (72 chars or less) title summarizing the change.
- They should also include a body with more detailed explanatory text, wrapped to 72 characters.
- The blank line separating the summary from the body is critical (unless you omit the body entirely).
- Commit messages should be written in the imperative: "Implement feature" and not "Implemented feature".
- Bulleted points are fine.
- Typically a hyphen or asterisk is used for the bullet, followed by a single space.
Use the pull request template to provide a complete description of the change. The template aims to capture important information to streamline the review process, ensure your changes are captured in release notes, and update related issues. Your pull request description and any discussion that follows is a contribution itself that will help the community and future contributors understand the project better.
- Before submitting a pull request, please make sure you verify the changes
locally. The
Makefilein this repository provides useful targets such aslintandtestto make verification easier. - Prefer small commits and small pull requests over large changes. Small changes are easier to digest and get reviewed faster. If you find that your change is getting large, break up your PR into small, logical commits. Consider breaking up large PRs into smaller PRs, if each of them can be useful on its own.
- Have good commit messages. Please see Commit Messages section for guidelines.
- Pull requests should reference an existing issue and include a
Closes|Fixes|Resolves #NNNNorUpdates #NNNNcomment. Remember thatFixeswill close the associated issue, andUpdateswill link the PR to it.
Once a pull request has been opened, the following must take place before it is merged:
- It needs to pass all the checks.
- It needs to be approved by a Maintainer for all files changed
While these steps will not always take place in the same order, the following describes the process for a typical pull request once it is opened:
- Review is automatically requested from Maintainers.
- Assignee is added to pull request to ensure it gets proper attention throughout the process. Typically one of the Maintainers will assign themselves, but they may choose to delegate to someone else.
- Assignee may request others to do an initial review; anyone else may review
- Reviewers leave feedback
- Contributor updates pull request to address feedback
- Requested reviewer approves pull request
- Assignee approves pull request
- Assignee merges pull request or requests another member to merge it if necessary.
During the review process itself, direct discussion among contributors and reviewers is encouraged.
Throughout the process, and until the pull request has been merged, the following should be transparent to the contributor:
- Has the pull request been assigned to anyone yet?
- Has someone been requested to review the pull request?
- Has the PR been approved by a reviewer?
- Has the PR been approved by the approver?
If any of the above is unclear, and there has been no new activity for 2-3 days, the contributor is encouraged to seek further information by commenting and mentioning the assignee or @cloudfoundry/cf-k8s if there is no assignee or they themselves are unresponsive.
Maintainers should prefer to merge pull requests with the Squash and merge option. This option is preferred for a number of reasons. First, it causes GitHub to insert the pull request number in the commit subject which makes it easier to track which PR changes landed in. Second, a one-to-one correspondence between pull requests and commits makes it easier to manage reverting changes.
At a maintainer's discretion, pull requests with multiple commits can be merged with the Rebase and merge option. Merging pull requests with multiple commits can make sense in cases where a change involves code generation or mechanical changes that can be cleanly separated from semantic changes. The maintainer should review commit messages for each commit and make sure that each commit builds and passes tests.
All contributors to this project must have a signed Contributor License Agreement ("CLA") on file with us. The CLA grants us the permissions we need to use and redistribute your contributions as part of the project; you or your employer retain the copyright to your contribution. Before a PR can pass all required checks, our CLA action will prompt you to accept the agreement. Head over to the Linux Foundation EasyCLA.
Note: a signed CLA is required even for minor updates. If you see something trivial that needs to be fixed, but are unable or unwilling to sign a CLA, the maintainers will be happy to make the change on your behalf. If you can describe the change in a bug report, it would be greatly appreciated.