Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend CONTRIBUTING docs. #153

Merged
merged 8 commits into from
Oct 27, 2022
Merged

Extend CONTRIBUTING docs. #153

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
036ae22
docs: Structure commit message rules better.
programmiri Oct 26, 2022
aa8a931
docs: Correct grammar and spelling.
programmiri Oct 26, 2022
574ac69
docs: Add table of content.
programmiri Oct 26, 2022
fd2309d
docs: Add draft for missing sections.
programmiri Oct 26, 2022
fa903fa
docs: Correct info and fix a typo.
programmiri Oct 26, 2022
30d85ad
docs: Improve grammar.
programmiri Oct 26, 2022
c71e71e
docs: Update wording.
programmiri Oct 26, 2022
5e064e7
Update wording.
programmiri Oct 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 100 additions & 21 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,130 @@

🎉 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

```
<prefix>: <description>

[optional body]

```

**1. Add a short description as first line**
#### 1. Add a short description as the first line
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**
Expand All @@ -57,9 +134,9 @@ The first line (`<description>`) 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... <do your change>"_.

**⛔️ Don't**
Expand All @@ -70,11 +147,13 @@ The first line (`<description>`) 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**
```
Expand All @@ -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.