From cd0d2bfdea3a625cadcb10a50964ec8cbbd71d0a Mon Sep 17 00:00:00 2001 From: quexeky Date: Tue, 5 Nov 2024 12:04:29 +1100 Subject: [PATCH] docs: updated CONTRIBUTING.md Signed-off-by: quexeky --- CONTRIBUTING.md | 241 ++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 4 +- 2 files changed, 234 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4913841..35ef7e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,235 @@ -# Work In Progress -# Contributing -Welcome! We're very happy to have people along with us to help creating Drop. +# CONTRIBUTING GUIDELINES -The best way to get started is by browsing our [GitHub Issues](https://github.com/Drop-OSS/drop/issues). +Drop is a community-driven project. Contribution is welcome, encouraged, and appreciated. +It is also essential for the development of the project. -## Etiquette -It might not be the most enjoyable part, but we're trying to foster a good community around Drop. +First, please take a moment to review our [code of conduct](CODE_OF_CONDUCT.md). -1. **Be respectful**. We're all doing our best, so please, think before you say anything. Criticism is fine, welcome even. But don't go out of your way to make someone's day worse. -2. **Don't ping anyone without a reason**. People only have a limited amount of time in their day, so unless it's either urgent or very specific to someone, keep the pings down. -3. **Just use common sense**. If you wouldn't do it to another repo, then don't do it here. Any questions can be asked either in discussions or in the [discord](https://discord.gg/ZVGggfXN) \ No newline at end of file +These guidelines are an attempt at better addressing pending +issues and pull requests. Please read them closely. + +Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution +you would make is not already covered. + + + +- [Reporting Issues](#reporting-issues) + - [You have a problem](#you-have-a-problem) + - [You have a suggestion](#you-have-a-suggestion) +- [Submitting Pull Requests](#submitting-pull-requests) + - [Getting started](#getting-started) + - [You have a solution](#you-have-a-solution) + - [You have an addition](#you-have-an-addition) +- [Use the Search, Luke](#use-the-search-luke) +- [Commit Guidelines](#commit-guidelines) + - [Format](#format) + - [Style](#style) +- [Volunteer](#volunteer) + + + +## Reporting Issues + +### You have a problem + +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your problem. + +If you find one, comment on it, so we know more people are experiencing it. + + +If you cannot find an existing issue, you can go ahead and create an issue with as much +detail as you can provide. +It should include the data gathered as indicated above, along with the following: + +1. How to reproduce the problem +2. What the correct behavior should be +3. What the actual behavior is + +Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle +(starting with `@`) in your message. + +We will do our very best to help you. + +### You have a suggestion + +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your suggestion. + +If you find one, comment on it, so we know more people are supporting it. + +If not, you can go ahead and create an issue. Please copy to anyone relevant (e.g. plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. + +## Submitting Pull Requests + +### Getting started + +You should be familiar with the basics of +[contributing on GitHub](https://help.github.com/articles/using-pull-requests) + + +You MUST always create PRs with _a dedicated branch_ based on the latest upstream tree. + +If you create your own PR, please make sure you do it right. Also be so kind as to reference +any issue that would be solved in the PR description body, +[for instance](https://help.github.com/articles/closing-issues-via-commit-messages/) +_"Fixes #XXXX"_ for issue number XXXX. + +### You have a solution + +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your [problem](#you-have-a-problem), and any pending/merged/rejected PR covering your solution. + +If the solution is already reported, try it out and +1 the pull request if the +solution works ok. On the other hand, if you think your solution is better, post +it with reference to the other one so we can have both solutions to compare. + +If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. + +### You have an addition + +We are absolutely accepting more contributions or features to drop, but please, make sure +that it is reasonable. Contributions that only cover a very small niche are likely to not +be added. + +Please be so kind as to [search](#use-the-search-luke) for any pending, merged or rejected Pull Requests +covering or related to what you want to add. + +If you find one, try it out and work with the author on a common solution. + +If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. + +For any extensive change, such as API changes, you will have to find testers to +1 your PR. + +---- + +## Use the Search, Luke + +_May the Force (of past experiences) be with you_ + +GitHub offers [many search features](https://help.github.com/articles/searching-github/) +to help you check whether a similar contribution to yours already exists. Please search +before making any contribution, it avoids duplicates and eases maintenance. Trust me, +that works 90% of the time. + +You can also take a look at the [FAQ](https://github.com/Drop-OSS/docs/wiki/FAQ) +to be sure your contribution has not already come up. + +If all fails, your thing has probably not been reported yet, so you can go ahead +and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests). + +---- + +## Commit Guidelines + +Drop uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +specification. The automatic changelog tool uses these to automatically generate +a changelog based on the commit messages. Here's a guide to writing a commit message +to allow this: + +### Format + +``` +type(scope)!: subject +``` + +- `type`: the type of the commit is one of the following: + + - `feat`: new features. + - `fix`: bug fixes. + - `docs`: documentation changes. + - `refactor`: refactor of a particular code section without introducing + new features or bug fixes. + - `style`: code style improvements. + - `perf`: performance improvements. + - `test`: changes to the test suite. + - `ci`: changes to the CI system. + - `build`: changes to the build system (we don't yet have one so this shouldn't apply). + - `chore`: for other changes that don't match previous types. This doesn't appear + in the changelog. + +- `scope`: section of the codebase that the commit makes changes to. If it makes changes to + many sections, or if no section in particular is modified, leave blank without the parentheses. + Examples: + + - Commit that changes the `git` plugin: + ``` + feat(git): add alias for `git commit` + ``` + + - Commit that changes many plugins: + ``` + style: fix inline declaration of arrays + ``` + + For changes to plugins or themes, the scope should be the plugin or theme name: + + - ✅ `fix(agnoster): commit subject` + - ❌ `fix(theme/agnoster): commit subject` + +- `!`: this goes after the `scope` (or the `type` if scope is empty), to indicate that the commit + introduces breaking changes. + + Optionally, you can specify a message that the changelog tool will display to the user to indicate + what's changed and what they can do to deal with it. You can use multiple lines to type this message; + the changelog parser will keep reading until the end of the commit message or until it finds an empty + line. + + Example (made up): + + ``` + style(agnoster)!: change dirty git repo glyph + + BREAKING CHANGE: the glyph to indicate when a git repository is dirty has + changed from a Powerline character to a standard UTF-8 emoji. You can + change it back by setting `ZSH_THEME_DIRTY_GLYPH`. + + Fixes #420 + + Co-authored-by: Username + ``` + +- `subject`: a brief description of the changes. This will be displayed in the changelog. If you need + to specify other details, you can use the commit body, but it won't be visible. + + Formatting tricks: the commit subject may contain: + + - Links to related issues or PRs by writing `#issue`. This will be highlighted by the changelog tool: + ``` + feat(archlinux): add support for aura AUR helper (#9467) + ``` + + - Formatted inline code by using backticks: the text between backticks will also be highlighted by + the changelog tool: + ``` + feat(shell-proxy): enable unexported `DEFAULT_PROXY` setting (#9774) + ``` + +### Style + +Try to keep the first commit line short. It's harder to do using this commit style but try to be +concise, and if you need more space, you can use the commit body. Try to make sure that the commit +subject is clear and precise enough that users will know what changed by just looking at the changelog. + +---- + +## Volunteer + +Very nice!! :) + +Please have a look at the [Volunteer](https://github.com/ohmyzsh/ohmyzsh/wiki/Volunteers) +page for instructions on where to start and more. + +## Reference +This contributing guide is adapted from the +[oh-my-zsh contribution guide](https://github.com/ohmyzsh/ohmyzsh/blob/master/CONTRIBUTING.md). +If there are any issues with this, please email (admin@quexeky.dev)[mailto://admin@quexeky.dev]. \ No newline at end of file diff --git a/README.md b/README.md index 56f51bc..a25180e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@
- Contribution guide    + Contribution guide    Our website   

@@ -11,7 +11,7 @@ [![GitHub License](https://img.shields.io/github/license/Drop-OSS/drop-app)](LICENSE) ![Gitlab Pipeline Status](https://img.shields.io/gitlab/pipeline-status/drop-oss%2Fdrop?gitlab_url=https%3A%2F%2Flab.deepcore.dev) [![Discord](https://img.shields.io/discord/1291622805124812871?label=discord)](https://discord.gg/ZVGggfXN) -[![Static Badge](https://img.shields.io/badge/contributions-welcome-blue)](https://github.com/Drop-OSS/drop/blob/main/README.md) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) # Drop