diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ccf41f3a05..78006e0479 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,45 +2,122 @@ 🎉 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. +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](https://opensource.guide/how-to-contribute/). -Please read through this document before submitting any issues or pull requests. This ensures all parties have all necessary information to respond to your bug report or contribution. +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. +## Content -## ❤ī¸ Code of Conduct +- [❤ī¸ Code of Conduct](#code-of-conduct) +- [Opening an issue](#opening-an-issue) +- [How to work on an issue](#how-to-work-on-an-issue) +- [How to make a pull request](#how-to-make-a-pull-request) + - [When is your pull request ready to be merged?](#when-is-your-pull-request-ready-to-be-merged) +- [Guideline commit messages](#guideline-commit-messages) + - [ℹī¸ Semantic prefixes for commit messages](#-semantic-prefixes-for-commit-messages) + - [✍ī¸ Writing a great commit message](#-writing-a-great-commit-message) + +## ❤ī¸ Code of Conduct This project has adopted the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). 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](https://www.contributor-covenant.org/faq/). + +## Opening an issue +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? + + +## How to work on an issue + +- 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](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the Klaw repository. +- On your fork, [create a branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/managing-branches#creating-a-branch) named after the issue you're working on. +- Make all of your changes 🧑‍đŸ’ģ +- For your commits, please see our [Guideline commit messages](#guideline-commit-messages). +- 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 🎉 + + +## How to make a pull request + +GitHub has detailed documentation on [how to create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) 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. + + +### ✅ When is your pull request ready to be merged? + +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 `main` should be treated like we release it into production right away. +- The `main` branch should always be in a state where it can be deployed and used right away. + +__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](#guideline-commit-messages). +- 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. + + ## Guideline commit messages -We uses the [Conventional Commits](https://www.conventionalcommits.org/) specification. It helps us creating a helpful and explicit git history. +We use the [Conventional Commits](https://www.conventionalcommits.org/) specification. It helps to create a meaningful and explicit git history. ### ℹī¸ Semantic prefixes for commit messages - **fix**: a commit that patches a bug. -Example: `fix: Removes circular dependency` + Example: `fix: Removes circular dependency` - **feat**: a commit that introduces a new feature. -Example: `feat: Add sorting to user list` + 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` + 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` + Example: `refactor: Update footer from kafkawize.io to klaw-project.io` ### ✍ī¸ Writing a great commit message -A "great" commit message enables others to gain more context about a code change. While the `diff` is telling you **what** has changes, the commit message can tell you **why** it has changed. +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](https://cbea.ms/git-commit/). We used it as a base for our rules. - -#### Rules - ``` : @@ -48,7 +125,7 @@ For more information read this article: [How to Write a Git Commit Message](http ``` -**1. Add a short description as first line** +#### 1. Add a short description as the first line The first line (``) should be a short description of your change. Limit it to preferably 50 characters. It never should be longer than 72 characters. **⛔ī¸ Don't** @@ -57,9 +134,9 @@ The first line (``) should be a short description of your change. L **ī¸âœ… Do** -`Add first iteration for contribution guide` +`Add the first iteration for contribution guide` -**2. Use the "imperative mood" in first line** +#### 2. Use the "imperative mood" in the first line "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** @@ -70,11 +147,13 @@ The first line (``) should be a short description of your change. L `fix: Remove the newline that caused a linting error` -> _"If applied, this commit will_ remove the newline that caused a linting error" -**3. Separate your description with a new line from the body.** -If you add an 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 useable. -**4. Use an optional body to explain why, not how.** -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. +#### 3. Separate your description with a new line from the body +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. + + +#### 4. Use an optional body to explain why not how. +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** ``` @@ -87,8 +166,8 @@ Change "optoinal" "to optional" **ī¸âœ… Do** ```fix: Remove word -Remove "just" from description, because it can make people feel inadequate. +Remove "just" from the description, because it can make people feel inadequate. ``` -**5. Wrap your body at 72 characters** +#### 5. Wrap your body at 72 characters Git does not wrap text, so you have to take care of margins. Editors and IDEs can help with that.