|
| 1 | +# Contributing to Quotepedia API |
| 2 | + |
| 3 | +> [!WARNING] |
| 4 | +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. |
| 5 | +
|
| 6 | +Thank you for contributing! |
| 7 | + |
| 8 | +Every contribution is welcome. First, please read the relevant section before contributing to ensure a smooth process for everyone. The community appreciates your support! |
| 9 | + |
| 10 | +> In case if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: |
| 11 | +> |
| 12 | +> - Star the project |
| 13 | +> - Refer this project in your project's readme |
| 14 | +> - Mention the project at local meetups and tell your friends or colleagues |
| 15 | +
|
| 16 | +## I have a Question |
| 17 | + |
| 18 | +Before you ask a question, it's best to search for existing [issues](/issues). In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. |
| 19 | + |
| 20 | +If you then still feel the need to ask a question and need clarification, we recommend the following: |
| 21 | + |
| 22 | +- Open an [issue](/issues/new) with corresponding tags. |
| 23 | +- Provide as much context as you can about what you're running into. |
| 24 | +- Provide project and platform versions (python, pdm, etc), depending on what seems relevant. |
| 25 | + |
| 26 | +We will then take care of the issue as soon as possible. |
| 27 | + |
| 28 | +## Reporting Bugs |
| 29 | + |
| 30 | +> [!WARNING] |
| 31 | +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent to organization members. |
| 32 | +
|
| 33 | +We use issues to track bugs and errors. When experiencing issues with this project, please open a [bug report issue](/issues/new?template=bug_report.yaml). |
| 34 | + |
| 35 | +Once it's submitted: |
| 36 | + |
| 37 | +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. |
| 38 | +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#code-contribution). |
| 39 | + |
| 40 | +## Requesting Features |
| 41 | + |
| 42 | +> [!NOTE] |
| 43 | +> Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on. |
| 44 | +
|
| 45 | +We use issues to track feature requests. To suggest an enhancement, please open a [feature request issue](/issues/new?template=feature_request.yaml). |
| 46 | + |
| 47 | +Once it's submitted: |
| 48 | + |
| 49 | +- Our team will review and discuss your suggestion. |
| 50 | + |
| 51 | +## Code Contribution |
| 52 | + |
| 53 | +### Prerequisites |
| 54 | + |
| 55 | +- [**Python**](https://www.python.org/downloads/): Ensure you have the required minimum version specified in the [`pyproject.toml`](pyproject.toml). |
| 56 | +- [**PDM**](https://pdm-project.org/): This project uses **pdm instead of pip** for convenient scripts and dependency management. |
| 57 | +- [**PostgreSQL**](https://www.postgresql.org/download): Set up and create a PostgreSQL database for data storage. |
| 58 | +- [**Redis**](https://redis.io/download): Start a new redis service for caching and data storage. |
| 59 | +- **SMTP Server**: Set up an SMTP server for mailings. |
| 60 | + |
| 61 | +### Submitting PRs |
| 62 | + |
| 63 | +If you encounter any issues or are unsure about what to work on, please search for "TODO" comments in the project code. These comments indicate tasks that need to be completed. For example, you might find something like this: |
| 64 | + |
| 65 | +```python |
| 66 | +# TODO: Optimize this function to improve performance and reduce execution time. |
| 67 | +``` |
| 68 | + |
| 69 | +These notes can guide you on areas that require attention or improvement. |
| 70 | + |
| 71 | +#### Step 1 — Clone the repository |
| 72 | + |
| 73 | +To start contributing to the project, fork it first and then clone your fork to your local machine using git: |
| 74 | + |
| 75 | +- Clone using the web URL: |
| 76 | + ```sh |
| 77 | + git clone https://github.com/quotepedia/api.git |
| 78 | + ``` |
| 79 | +- Use a password-protected SSH key: |
| 80 | + ```sh |
| 81 | + git clone [email protected]:quotepedia/api.git |
| 82 | + ``` |
| 83 | +- Work with official GitHub CLI: |
| 84 | + ```sh |
| 85 | + gh repo clone quotepedia/api |
| 86 | + ``` |
| 87 | + |
| 88 | +#### Step 2 — Configure environment |
| 89 | + |
| 90 | +Create a [`config.yaml`](config.yaml) file in the project root directory and populate it based on the example in [`config.sample.yaml`](config.sample.yaml). |
| 91 | + |
| 92 | +Then, run the following commands to set up your environment: |
| 93 | + |
| 94 | +```sh |
| 95 | +pdm install |
| 96 | +pdm i18n:compile |
| 97 | +pdm run alembic upgrade head |
| 98 | +``` |
| 99 | + |
| 100 | +#### Step 3 — Make changes |
| 101 | + |
| 102 | +> ![IMPORTANT] |
| 103 | +> Please adhere to the code style used throughout the project. |
| 104 | +
|
| 105 | +Contributions can vary from simple [`README.md`](README.md) updates to bug fixes or new features. Depending on the nature of your contribution, you may need to follow additional steps outlined below. Focus on the updates you wish to merge into this repository. |
| 106 | + |
| 107 | +#### Step 4 — Write tests |
| 108 | + |
| 109 | +We strive to maintain comprehensive test coverage in our codebase. All the tests are located in the [`tests`](tests/) folder. |
| 110 | + |
| 111 | +#### Step 5 — Update documentation |
| 112 | + |
| 113 | +We recommend you to review the [`README.md`](README.md) and look for anything needs to be updated regarding the changes you made. |
| 114 | + |
| 115 | +#### Step 6 — Commit changes |
| 116 | + |
| 117 | +Before committing your changes, run these scripts to ensure everything is fine: |
| 118 | + |
| 119 | +```sh |
| 120 | +pdm format |
| 121 | +pdm check |
| 122 | +pdm test |
| 123 | +``` |
| 124 | + |
| 125 | +#### Step 7 — Submit a pull request |
| 126 | + |
| 127 | +Once you are satisfied with your changes: [submit a pull request](/compare). |
| 128 | + |
| 129 | +Your efforts help improve the project for everyone! |
| 130 | + |
| 131 | +### Commit Messages |
| 132 | + |
| 133 | +We're following the [Conventional Commits](https://www.conventionalcommits.org) specification for adding human and machine readable meaning to commit messages. |
| 134 | + |
| 135 | +## Localization |
| 136 | + |
| 137 | +We utilize [gettext](https://www.gnu.org/software/gettext/) for internationalization (i18n) purposes in our API. This approach enables us to create high-quality client apps that can localize error messages out of the box. |
| 138 | + |
| 139 | +### Supported Languages |
| 140 | + |
| 141 | +- English ([en](src/i18n/locales/en/)) |
| 142 | +- Russian ([ru](src/i18n/locales/ru/)) |
| 143 | + |
| 144 | +You can find a complete list of all supported locales [here](src/i18n/locales). For editing we recommend using [Poedit](https://poedit.net/) as a GUI. |
| 145 | + |
| 146 | +### Scripts |
| 147 | + |
| 148 | +We have three main i18n scripts defined in [`pyproject.toml`](pyproject.toml) that leverage [Babel's CLI](https://babel.pocoo.org) to manipulate translation messages: |
| 149 | + |
| 150 | +- **Extract**: Creates `messages.pot` (Portable Object Template) from files defined in [`babel.ini`](babel.ini): |
| 151 | + ```sh |
| 152 | + pdm i18n:extract |
| 153 | + ``` |
| 154 | +- **Update**: Modifies `messages.po` (Portable Object) for each locale that is sent to translators: |
| 155 | + ```sh |
| 156 | + pdm i18n:update |
| 157 | + ``` |
| 158 | +- **Compile**: Generates `messages.mo` (Machine Object) for each locale that is used at runtime: |
| 159 | + ```sh |
| 160 | + pdm i18n:compile |
| 161 | + ``` |
| 162 | + |
| 163 | +## Join The Project Team |
| 164 | + |
| 165 | +Contact the organization members in order to join the project team. |
0 commit comments