🎉 First off: Thank you for your interest in contributing to our project 🥳
Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community. GitHub Open Source guides have a great source about ways to How to Contribute to Open Source.
Please read through this document before submitting any issues or pull requests. This ensures all parties have all the necessary information to respond to your bug report or contribution.
- Contributing Guidelines
This project has adopted the Contributor Covenant Code of Conduct. Before contributing, please take the time to read our COC. Everyone participating is expected to uphold this code. Please report unacceptable behavior to us!
For more information see the Code of Conduct FAQ.
You should open an issue when you
- checked that there is no issue open already related to your topic
- want to report an error that you can't resolve by yourself
- want to propose a new feature
- want to discuss an idea to improve a higher-level topic, for example about community, documentation
What information does an issue need? The more information an issue includes, the better! For example:
- If it's a bug, describe in detail how to reproduce it. You can add screenshots or screen recordings for visual bugs.
- If it's a feature, create a user story. What problem does that feature solve? What value does it add?
-
Comment on the issue to inform that you will work on it.
-
If you have the rights: set yourself as an assignee and add the in progress label.
-
Fork the Klaw repository.
-
On your fork, create a branch named after the issue you're working on.
-
🧑💻 Make all of your changes. You may find detailed documentation about how to set up a local development environment in our documentation:
-
For your commits, please see our Guideline commit messages.
-
Prefer making small and self-contained commits. It helps doing reviews.
-
Check if it would be helpful to update documentation related to your change. If yes, please do so 🤗!
-
Make sure you add tests for your changes.
-
If you fix a bug, add a regression test.
-
When you're finished and pushed all your changes to GitHub, you're ready to create a pull request 🎉
GitHub has detailed documentation on how to create a PR if you want to have more information. If you're not sure what to do, please feel free to reach out to our community!
Be conscious of the scope of one PR. Sometimes it is tempting to get sidetracked for example by refactoring some unrelated code. We've all been there! But this should be a separate PR. Only add changes to your PR related and contribute to the issue you're solving.
Klaw project requires contributors to adhere to the Developer Certificate of Origin, this means you must sign off your commits. We automatically check that all commit messages contain the Signed-off-by: line with your name and email.
To sign off commits you need to add the -s (or --signoff) flag to your commit command. For example:
git commit -s -m"docs: Update contribution guide with DCO guidelines"
If you opened a Pull Request but not all commits were signed off, no worries, it can be fixed. If you had only one commit, go and amend it like follows:
git commit --amend --signoff
In case of having multiple commits, you can rebase and sign off, the following command with sign off the last 3 commits:
git rebase --signoff HEAD~3
Once you are done, you need to force push your changes. We recommend using --force-with-lease when force pushing:
git push --force-with-lease origin/your-branch-name
Every pull request has to be reviewed before merging. At least one maintainer needs to approve it. This is meant to assure the quality of the product. It is also a great tool to give and receive feedback in the community and learn from each other.
Your pull request should meet the following criteria to be ready for review:
1. Every PR has to be releasable
- Every PR that is merged on
mainshould be treated like we release it into production right away. - The
mainbranch should always be in a state where it can be deployed and used right away. - If API changes were made, ensure the
openapi.yamlspec was generated and added to the commit, and that the frontend types have been generated withpnpm extract-api-types. Read about why here. - All GitHub actions checks must be green.
2. A clear goal with a small scope
- Make small and incremental PRs.
- The code changes relate to one specific topic.
- Every PR should have one specific goal (and if you add that goal in your description - all the better).
- Rather do multiple smaller PRs than one big one! PRs with a lot of changes are difficult to review. It's also more demanding to give constructive feedback to them.
3. Add meaningful information
- A descriptive title and detailed description of your changes help the reviewer gaining context.
- Include links to relevant issues.
- If you followed a recommended approach e.g. from an article, link it in the PR.
- Especially for UI changes it can be helpful to add screenshots or recordings of your changes
- If you have questions, don't hesitate to add them!
4. Keep a clear git history in mind
- If you do multiple commits, try to make every commit cover the scope of your changes.
- Your commit messages should follow our guideline.
- If you add changes after a review, don't force push in your existing PR, but add new commits. That way, reviewers can pick up the review again.
A pull request author should never merge themselves. Pull requests are reviewed and merged by one or more maintainer(s).
The review process goes as follow:
- One or more maintainer(s) will carefully read the description and the code of the pull request
- Comments may be left on specific parts of the code, or on the pull request as a whole. We strive to always be empathetic and helpful in our reviews. The comments may be questions about technical choices, observations about possible improvements, clarification of some of the project's conventions, or compliments on beautiful code.
- Comments may be blocking. In these cases, the pull request will not be approved until the comments are addressed. "Addressing" a comment can mean explaining your approach and getting agreement from the reviewer, or implementing the suggested change and pushing a subsequent commit (we appreciate linking to the commit in an answer to the comment).
- Once all comments have been addressed and resolved, one or more maintainer will approve the pull request. This action means "this code should be part of Klaw".
- The pull request will then be merged into the
mainbranch by a maintainer, usually one of the reviewers.
In summary, the checklist for a pull request to be merged is as follow:
- Reviewed and approved by one or more maintainer(s)
- GitHub actions all green
- Pull request branch up to date with
mainbranch
While working on a change, making small commits related to specific changes is a good practice. The commit history helps describe the process of building. It helps reviewers doing a good job! But they can clutter the Git history on the main branch a lot.
This is why we use "squash and merge" as merge method. When merging, the small commits are combined into one. It creates a cleaner merge history. It also makes it more straight forward to revert all part of the changes, if that is needed.
The commit message for the pull request can be changed when merging. We recommend updating the automatically created text for this commit to create a meaningful squash commit message. They should follow our Guideline commit messages.
We use the Conventional Commits specification. It helps to create a meaningful and explicit git history.
-
fix: a commit that patches a bug. Example:
fix: Removes circular dependency -
feat: a commit that introduces a new feature. Example:
feat: Add sorting to user list -
docs: a commit that changes something related to documentation. Example:
docs: Update contribution guide with guidelines for commit messages -
refactor: a commit that refactors existing code. Example:
refactor: Update footer from kafkawize.io to klaw-project.io
A "great" commit message enables others to gain more context about a code change. While the diff is telling you what has changed, the commit message can tell you why it has changed.
For more information read this article: How to Write a Git Commit Message. We used it as a base for our rules.
<prefix>: <description>
[optional body]
The first line (<description>) should be a short description of your change. Limit it to preferably 50 characters. It never should be longer than 72 characters.
⛔️ Don't
Add CONTRIBUTING.md with first information about Code Of Conduct and a guideline for commit messages that includes our first rules and pattern we want to establish
️✅ Do
Add the first iteration for contribution guide
"Imperative mood" means you form a sentence as if you were giving a command. You can image your commit message completing the sentence "If applied, this commit will... ".
⛔️ Don't
fix: Removed the newline that caused a linting error
-> "If applied, this commit will removed the newline that caused a linting error"
️✅ Do
fix: Remove the newline that caused a linting error
-> "If applied, this commit will remove the newline that caused a linting error"
If you add a body, add an empty line between your description to separate it from the body. This makes the message more readable. It also makes git log --oneline or git shortlog more usable.
You don't need to explain the code! The commit message has a changeset that contains this information. Use the body to explain why you made a change. Not every commit needs to have a body. Often the code change itself is explanation enough.
⛔️ Don't
fix: Fix typo
Change "optoinal" "to optional"
️✅ Do
Remove "just" from the description, because it can make people feel inadequate.
Git does not wrap text, so you have to take care of margins. Editors and IDEs can help with that.