Become one of the contributors to this project! We thrive to build a welcoming and open community for anyone who wants to use the project or contribute to it. There are just a few small guidelines you need to follow. To help us create a safe and positive community experience for all, we require all participants to adhere to the Code of Conduct.
- Become a contributor
- Submitting issues
- Triage issues
- Your first contribution
- Branching
- Signing your commits
- Pull requests
- Code reviews
- TODOs in the code
You can contribute to this project in several ways. Here are some examples:
- Contribute to the documentation and codebase.
- Report and triage bugs.
- Create feature requests
- Fix bugs and implement features
- Write technical documentation and blog posts, for users and contributors.
- Help others by answering questions about this project.
All issues related to CSM, regardless of the repository the issue belongs to, should be submitted here. Issues will be triaged and labels will be used to indicate the type of issue. This section outlines the types of issues that can be submitted.
We aim to track and document everything related to CSM via the Issues page. The code and documentation are released with no warranties or SLAs and are intended to be supported through a community driven process.
Before submitting a new issue, make sure someone hasn't already reported the problem. Look through the existing issues for similar issues.
Report a bug by submitting a bug report. Make sure that you provide as much information as possible on how to reproduce the bug.
When opening a Bug please include the following information to help with debugging:
- Version of relevant software: this software, Kubernetes, Dell Storage Platform, Helm, etc.
- Details of the issue explaining the problem: what, when, where
- The expected outcome that was not met (if any)
- Supporting troubleshooting information. Note: Do not provide private company information that could compromise your company's security.
An Issue must be created before submitting any pull request. Any pull request that is created should be linked to an Issue.
If you have an idea of how to improve this project, submit a feature request.
If you have a question and you can't find the answer in the documentation or issues, the next step is to submit a question.
We'd love your help answering questions being asked by other CSM users.
Triage helps ensure that issues resolve quickly by:
- Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for an issue to explain how an end user experiences a problem and what actions they took.
- Giving a contributor the information they need before they commit to resolving an issue.
- Lowering the issue count by preventing duplicate issues.
- Streamlining the development process by preventing duplicate discussions.
If you don't have the knowledge or time to code, consider helping with issue triage. The CSM community will thank you for saving them time by spending some of yours.
Read more about the ways you can Triage issues.
Unsure where to begin contributing? Start by browsing issues labeled beginner friendly or help wanted.
- Beginner-friendly issues are generally straightforward to complete.
- Help wanted issues are problems we would like the community to help us with regardless of complexity.
When you're ready to contribute, it's time to create a pull request.
CSM follows a scaled trunk branching strategy where short-lived branches are created off of the main branch. When coding is complete, the branch is merged back into main after being approved in a pull request code review.
- Fork the repository.
- Create a branch off of the main branch.
- Make your changes and commit them to your branch.
- If other code changes have merged into the upstream main branch, perform a rebase of those changes into your branch.
- Open a pull request between your branch and the upstream main branch.
- Once your pull request has merged, your branch can be deleted.
We require that developers sign off their commits to certify that they have permission to contribute the code in a pull request. This way of certifying is commonly known as the Developer Certificate of Origin (DCO). We encourage all contributors to read the DCO text before signing a commit and making contributions.
GitHub will prevent a pull request from being merged if there are any unsigned commits.
GPG (GNU Privacy Guard) will be used to sign commits. Follow the instructions here to create a GPG key and configure your GitHub account to use that key.
Make sure you have your user name and e-mail set. This will be required for your signed commit to be properly verified. Check the following references:
Once Git and your GitHub account have been properly configured, you can add the -S flag to the git commits:
$ git commit -S -m your commit message
# Creates a signed commitCSM uses the guidelines for commit messages outlined in How to Write a Git Commit Message
If this is your first time contributing to an open-source project on GitHub, make sure you read about Creating a pull request.
A pull request must always link to at least one GitHub issue. If that is not the case, create a GitHub issue and link it.
To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines:
- Title and description matches the implementation.
- Commits within the pull request follow the formatting guidelines.
- The pull request closes one related issue.
- The pull request contains necessary tests that verify the intended behavior.
- If your pull request has conflicts, rebase your branch onto the main branch.
If the pull request fixes a bug:
- The pull request description must include
Fixes #<issue number>. - To avoid regressions, the pull request should include tests that replicate the fixed bug.
The CSM team squashes all commits into one when we accept a pull request. The title of the pull request becomes the subject line of the squashed commit message. We still encourage contributors to write informative commit messages, as they becomes a part of the Git commit body.
We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible.
Make sure that the title for your pull request uses the same format as the subject line in the commit message.
GitHub Actions are used to enforce quality gates when a pull request is created or when any commit is made to the pull request. These GitHub Actions enforce our minimum code quality requirement for any code that get checked into the CSM Go code repository. If any of the quality gates fail, it is expected that the contributor will look into the check log, understand the problem and resolve the issue. If help is needed, please feel free to reach out the maintainers of the project for support.
- Golang Security Checker inspects source code for security vulnerabilities by scanning the Go AST.
- Malware Scanner inspects source code for malware.
- Container Scanner scans containers for security vulnerabilities.
GitHub action that analyzes source code to report suspicious constructs such as Printf calls whose arguments do not align with the format string, abnormal or not used code in pull requests. Please refer to vet for more information.
GitHub action that analyzes source code to flag programming errors, stylistics errors, and suspicious constructs. Please refer to Go lint for more information.
GitHub action that analyzes source code to flag formatting errors. Please refer to gofmt for more information.
GitHub action that analyzes source code for non-inclusive words and language.
GitHub action that runs Go unit tests and checks that the code coverage of each package meets a configured threshold (currently 90%). An error is flagged if a given pull request does not meet the test coverage threshold and blocks the pull request from being merged.
All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.
A pull request must satisfy following for it to be merged:
- A pull request will require at least 2 maintainer approvals, one of which must come from a code owner.
- Maintainers must perform a review to ensure the changes adhere to guidelines laid out in this document.
- If any commits are made after the PR has been approved, the PR approval will automatically be removed and the above process must happen again.
For the Go code in the CSM repository, we expect the code styling outlined in Effective Go. In addition to this, we have the following supplements:
See Effective Go for details on handling errors.
Do not discard errors using _ variables. If a function returns an error, check it to make sure the function succeeded. Handle the error, return it, or, in truly exceptional situations, panic. This can be checked using the errcheck tool if you have it installed locally.
Do not log the error if it will also be logged by a caller higher up the call stack; doing so causes the logs to become repetitive. Instead, consider wrapping the error in order to provide more detail. To see practical examples of this, see this bad practice and this preferred practice:
package main
import (
"errors"
"log"
)
func main() {
err := foo()
if err != nil {
log.Printf("error: %+v", err)
return
}
}
func foo() error {
err := bar()
if err != nil {
log.Printf("error: %+v", err)
return err
}
return nil
}
func bar() error {
return errors.New("something bad happened")
}package main
import (
"errors"
"fmt"
"log"
)
func main() {
err := foo()
if err != nil {
log.Printf("error: %+v", err)
return
}
}
func foo() error {
err := bar()
if err != nil {
return fmt.Errorf("calling bar: %w", err)
}
return nil
}
func bar() error {
return errors.New("something bad happened")
}Do not use the github.com/pkg/errors package as it is now in maintenance mode since Go 1.13+ added official support for error wrapping. See go1.13-errors and errwrap for more information.
Run gofmt on your code to automatically fix the majority of mechanical style issues. Almost all Go code in the wild uses gofmt. The rest of this document addresses non-mechanical style points.
An alternative is to use goimports, a superset of gofmt which additionally adds (and removes) import lines as necessary.
A recommended approach is to ensure your editor supports running of goimports automatically on save.
We don't like TODOs in the code or documentation. It is really best if you sort out all issues you can see with the changes before we check the changes in.