# CONTRIBUTING GUIDELINES Drop is a community-driven project. Contribution is welcome, encouraged, and appreciated. It is also essential for the development of the project. First, please take a moment to review our [code of conduct](CODE_OF_CONDUCT.md). 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) - [Development](#development) - [Note: `--optional` flag is **REQUIRED**](#note-optional-flag-is-required) - [Tech Stack](#tech-stack) - [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) - [Translation](#translation) - [Commit Guidelines](#commit-guidelines) - [Format](#format) - [Style](#style) ## 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. ## Development To get started with development, you need `yarn` and `docker compose` installed (or know how to set up a PostgreSQL database). Steps: 1. Run `git submodule update --init --recursive` to setup submodules 1. Copy the `.env.example` to `.env` and add any api keys you need to use (e.g. for the Giant Bomb API) - You can find other configuration options in the [documentation](https://docs.droposs.org/) 1. Create the `.data` directory with `mkdir .data` 1. Ensure that your user owns the `.data` directory with `sudo chown -R $(id -u $(whoami))` 1. Open up a terminal and navigate to `dev-tools`, and run `docker compose up` 1. Open up another terminal in the root directory of the project and run `yarn` and then `yarn prisma migrate dev` to setup the database 1. Run `yarn dev` to start the development server As part of the first-time bootstrap, Drop creates an invitation with the fixed id of 'admin'. So, to create an admin account, go to: http://localhost:3000/auth/register?id=admin ### Tech Stack This repo uses the Nuxt 3 + TailwindCSS stack, with the `yarn` package manager. For the database, Drop uses Prisma connected to PostgreSQL. ## 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). --- ## Translation If you want to help translate Drop, we would love to have your help! You can do so on our [weblate instance](https://translate.droposs.org/engage/drop/). Please make sure to **read** the [message format syntax](https://vue-i18n.intlify.dev/guide/essentials/syntax.html) page before starting. We use this special syntax to enable high quality translations, and failure to do so may result in your translations **causing errors** in Drop. ## 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. - `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. --- ## 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@deepcore.dev.