Thanks for taking the time to contribute! The following is a set of guidelines for contributing to our project. We encourage everyone to follow them with their best judgement.
Pull requests let you tell others about changes you have pushed to a branch in our repository. They are a dedicated forum for discussing the implementation of the proposed feature or bugfix between committer and reviewer(s).
This is an essential mechanism to maintain or improve the quality of our codebase, so let's see what we look for in a pull request.
The following are all formal requirements to be met before considering the content of the proposed changes.
Here we cover the configuration of the tools that will help you write code that complies with our standards and also the good practices that will make your contribution as useful as it can be!
First things first, Git is the base from which everything is built upon, so we want to make it as solid as possible.
- Start off by configuring your
user.nameanduser.emailas seen in Customizing Git. Theuser.emailparameter should always be the VMware corporate one. For your convenience, here is a good resource on Maintaining Different Git Identities. - Next, we want to be able to verify that commits are actually from a trusted source, so we are going to sign and verify our work with GPG.
- GitHub has a neat set of guides that will help you check for existing GPG keys, generate a new GPG key in case you don't already have one, tell Git about your signing key and of course show you how to sign commits.
- Finally, we want to publish our work and only our work. There is one thing that might bother us and the people we work with: line endings.
- Fortunately, GitHub has us covered again, check Configuring Git to handle line endings for Mac, Windows and Linux.
There's a Golden Rule when adressing code changes: Modify only what is related to the task.
When developing the next feature or bugfix we should also strive for small, atomic commits or, in other words, commits that group changes focused on one context and one context only. They are easier to read, understand, review, track and revert.
You can use Conventional Commits for commit message structure. A well-crafted Git commit message is the best way to communicate context about a change. Here is a good resource on How to Write a Git Commit Message or just skip to the guidelines.
Also, note that the commits will be squashed when merging the pull request, by doing a fast-forward merge. Regarding the squash commit message:
- If the PR contains a single commit, there won't be any squash and the commit will go directly to the target branch.
- If there are multiple commits, the message will default to the pull request title.
A final caveat to be aware of is that the fast-forward strategy requires that your branch is up-to-date with the target branch, so you will have to rebase / merge the target branch into your branch before merging the pull request.
The chart documentation is auto generated with helm-readme-generator, you can run it locally with docker, Pull request check will fail if documentation is no updated.
# On the repository root
docker run --rm \
-v $(pwd)/chart:/my_helm \
-w /my_helm \
helm-readme-generator readme-generator \
--readme README.md \
--values values.yamlWe use super- linter to maintain the files clean, you can run it locally with docker this way:
#Move to the root of the repository
## To lint all files in the repo run this command (takes long)
docker run --rm \
-e RUN_LOCAL=true \
-e USE_FIND_ALGORITHM=true \
-v $(pwd):/tmp/lint \
-w /tmp/lint ghcr.io/github/super-linter
# To lint a single file or directory
docker run --rm \
-e RUN_LOCAL=true \
-e USE_FIND_ALGORITHM=true \
-v $(pwd)/<your_file_or_directory>:/tmp/lint/<your_file_or_directory> -w /tmp/lint/ ghcr.io/github/super-linterThere are three important parts in a pull request:
- Title. Use a well descriptive but not too long message about what this change is about.
- Description. Do your best to put only relevant information. It is perfectly valid to leave it empty! But please, don't leave all your commit messages there.
- Destination branch. The destination branch is determined by the Branching Strategy section you can find below.
Additionally, there are other fields that can be useful:
- Asignee. Set one or multiple assignees.
Finally, when the work is still in progress remember to set the PR as draft like explaine in the GitHub documentation.
Git is our version control system for tracking changes in our codebase. As you may know, in Git's implementation, branching is really cheap! So we need an orderly, controlled way of dealing with them: Enter Branching Strategy. This is the set of rules in which we base our workflow.
stable.
- Protected branch
- Prevent changes without a pull request
- Changes come from a
featureorbugfixbranch - Merge strategy is always
--squash - Releases are triggered manually from this branch
feature branches
- One branch per feature
- May branch off from
stable - Naming convention is
feature/FEAT-NAME
bugfix branches
- One branch per bugfix
- May branch off from
stable - Naming convention is
bugfix/BUGFIX-NAME
revert branches
- One branch per revert
- May branch off from
stable - Naming convention is
revert/REVERT-NAME
Here there's one Golden Rule:
- Who pushes the changes, merges the changes. The author of the changes is the one who knows if the acceptance criteria of the related issue are completely met.
There is also a set of requirements to fulfill before merging a pull request:
- Wait for the PR-verify to be successful. PR-verify lets everyone know if your commits meet the conditions set for our repository.
- The acceptance criteria of the related issue are completely met.
- All comments by reviewers have been addressed.
- It is approved by whoever reviewed it.
- Sync before merge. So you verify that everything works as expected with the latest revision of the destination branch.