|
| 1 | +# Contributing to StarletteAdmin |
| 2 | + |
| 3 | +First off, thanks for taking the time to contribute! ❤️ |
| 4 | + |
| 5 | +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways |
| 6 | +to help and details about how this project handles them. Please make sure to read the relevant section before making |
| 7 | +your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The |
| 8 | +community looks forward to your contributions. 🎉 |
| 9 | + |
| 10 | +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support |
| 11 | +> the project and show your appreciation, which we would also be very happy about: |
| 12 | +> - Star the project |
| 13 | +> - Tweet about it |
| 14 | +> - Refer this project in your project's readme |
| 15 | +> - Mention the project at local meetups and tell your friends/colleagues |
| 16 | +
|
| 17 | +## Table of Contents |
| 18 | + |
| 19 | +- [Code of Conduct](#code-of-conduct) |
| 20 | +- [I Have a Question](#i-have-a-question) |
| 21 | +- [I Want To Contribute](#i-want-to-contribute) |
| 22 | + - [Reporting Bugs](#reporting-bugs) |
| 23 | + - [Suggesting Enhancements](#suggesting-enhancements) |
| 24 | + - [Your First Code Contribution](#your-first-code-contribution) |
| 25 | + - [Improving The Documentation](#improving-the-documentation) |
| 26 | + |
| 27 | +## Code of Conduct |
| 28 | + |
| 29 | +This project and everyone participating in it is governed by the |
| 30 | +[Starlette-Admin Code of Conduct](https://github.com/jowilf/starlette-admin/blob/master/CODE_OF_CONDUCT.md). |
| 31 | +By participating, you are expected to uphold this code. Please report unacceptable behavior |
| 32 | +to <hounonj@gmail.com>. |
| 33 | + |
| 34 | +## I Have a Question |
| 35 | + |
| 36 | +> If you want to ask a question, we assume that you have read the |
| 37 | +> available [Documentation](https://jowilf.github.io/starlette-admin/). |
| 38 | +
|
| 39 | +Before you ask a question, it is best to search for existing [Issues](https://github.com/jowilf/starlette-admin/issues) |
| 40 | +that might help you. In case you have found a suitable issue and still need clarification, you can write your question |
| 41 | +in this issue. It is also advisable to search the internet for answers first. |
| 42 | + |
| 43 | +If you then still feel the need to ask a question and need clarification, we recommend the following: |
| 44 | + |
| 45 | +- Open an [Issue](https://github.com/jowilf/starlette-admin/issues/new). |
| 46 | +- Provide as much context as you can about what you're running into. |
| 47 | +- Provide project and platform versions, depending on what seems relevant. |
| 48 | + |
| 49 | +We will then take care of the issue as soon as possible. |
| 50 | + |
| 51 | +## I Want To Contribute |
| 52 | + |
| 53 | +> ### Legal Notice |
| 54 | +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the |
| 55 | +> necessary rights to the content and that the content you contribute may be provided under the project license. |
| 56 | +
|
| 57 | +### Reporting Bugs |
| 58 | + |
| 59 | +#### Before Submitting a Bug Report |
| 60 | + |
| 61 | +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to |
| 62 | +investigate carefully, collect information and describe the issue in detail in your report. Please complete the |
| 63 | +following steps in advance to help us fix any potential bug as fast as possible. |
| 64 | + |
| 65 | +- Make sure that you are using the latest version. |
| 66 | +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment |
| 67 | + components/versions (Make sure that you have read the [documentation](https://jowilf.github.io/starlette-admin/). If |
| 68 | + you are looking for support, you might want to check [this section](#i-have-a-question)). |
| 69 | +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there |
| 70 | + is not already a bug report existing for your bug or error in |
| 71 | + the [bug tracker](https://github.com/jowilf/starlette-adminissues?q=label%3Abug). |
| 72 | +- Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have |
| 73 | + discussed the issue. |
| 74 | +- Collect information about the bug: |
| 75 | + - Stack trace (Traceback) |
| 76 | + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) |
| 77 | + - Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. |
| 78 | + - Possibly your input and the output |
| 79 | + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? |
| 80 | + |
| 81 | +#### How Do I Submit a Good Bug Report? |
| 82 | + |
| 83 | +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue |
| 84 | +> tracker, or elsewhere in public. Instead, sensitive bugs must be sent by email to <hounonj@gmail.com>. |
| 85 | +
|
| 86 | +We use GitHub issues to track bugs and errors. If you run into an issue with the project: |
| 87 | + |
| 88 | +- Open an [Issue](https://github.com/jowilf/starlette-admin/issues/new). (Since we can't be sure at this point whether |
| 89 | + it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) |
| 90 | +- Explain the behavior you would expect and the actual behavior. |
| 91 | +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to |
| 92 | + recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem |
| 93 | + and create a reduced test case. |
| 94 | +- Provide the information you collected in the previous section. |
| 95 | + |
| 96 | +Once it's filed: |
| 97 | + |
| 98 | +- The project team will label the issue accordingly. |
| 99 | +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no |
| 100 | + obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs |
| 101 | + with the `needs-repro` tag will not be addressed until they are reproduced. |
| 102 | +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such |
| 103 | + as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). |
| 104 | + |
| 105 | +### Suggesting Enhancements |
| 106 | + |
| 107 | +This section guides you through submitting an enhancement suggestion for StarletteAdmin, **including completely new |
| 108 | +features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the |
| 109 | +community to understand your suggestion and find related suggestions. |
| 110 | + |
| 111 | +#### Before Submitting an Enhancement |
| 112 | + |
| 113 | +- Make sure that you are using the latest version. |
| 114 | +- Read the [documentation](https://jowilf.github.io/starlette-admin/) carefully and find out if the functionality is |
| 115 | + already covered, maybe by an individual configuration. |
| 116 | +- Perform a [search](https://github.com/jowilf/starlette-admin/issues) to see if the enhancement has already been |
| 117 | + suggested. If it has, add a comment to the existing issue instead of opening a new one. |
| 118 | +- 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 |
| 119 | + convince the project's developers of the merits of this feature. Keep in mind that we want features that will be |
| 120 | + useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, |
| 121 | + consider writing an add-on/plugin library. |
| 122 | + |
| 123 | +#### How Do I Submit a Good Enhancement Suggestion? |
| 124 | + |
| 125 | +Enhancement suggestions are tracked as [GitHub issues](https://github.com/jowilf/starlette-admin/issues). |
| 126 | + |
| 127 | +- Use a **clear and descriptive title** for the issue to identify the suggestion. |
| 128 | +- Provide a **step-by-step description of the suggested enhancement** in as many details as possible. |
| 129 | +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point |
| 130 | + you can also tell which alternatives do not work for you. |
| 131 | +- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part |
| 132 | + which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS |
| 133 | + and Windows, and [this tool](https://github.com/colinkeenan/silentcast) |
| 134 | + or [this tool](https://github.com/GNOME/byzanz) on |
| 135 | + Linux. |
| 136 | +- **Explain why this enhancement would be useful** to most StarletteAdmin users. You may also want to point out the |
| 137 | + other projects that solved it better and which could serve as inspiration. |
| 138 | + |
| 139 | + |
| 140 | +### Your First Code Contribution |
| 141 | + |
| 142 | +#### Setting up the development environment |
| 143 | + |
| 144 | +We assume you are familiar with the general forking and pull request workflow for submitting to open-source projects. A |
| 145 | +complete guides is available [here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). |
| 146 | + |
| 147 | +StarletteAdmin uses [hatch](https://hatch.pypa.io/) to manage dependencies and packaging. |
| 148 | + |
| 149 | +Make sure hatch is installed globally: |
| 150 | + |
| 151 | +```shell |
| 152 | +pip install hatch |
| 153 | +``` |
| 154 | + |
| 155 | +#### Format |
| 156 | + |
| 157 | +To ensure code consistency StarletteAdmin uses [black](https://github.com/psf/black) |
| 158 | +and [ruff](https://github.com/charliermarsh/ruff) |
| 159 | + |
| 160 | +To clean all your code, run |
| 161 | + |
| 162 | +```hatch run format``` |
| 163 | + |
| 164 | +#### Testing |
| 165 | + |
| 166 | +StarletteAdmin uses [pytest](https://docs.pytest.org) for unit testing. To ensure the stability of StarletteAdmin, each |
| 167 | +added feature |
| 168 | +must be tested in a separate unit test. |
| 169 | + |
| 170 | +To run the test suite |
| 171 | + |
| 172 | +```shell |
| 173 | +hatch run test |
| 174 | +``` |
| 175 | + |
| 176 | +#### Submitting new code |
| 177 | + |
| 178 | +First, add the pre-commit command to your git's pre-commit hooks. This will ensure that you never forget to format your |
| 179 | +code |
| 180 | + |
| 181 | +```shell |
| 182 | +pre-commit install |
| 183 | +``` |
| 184 | + |
| 185 | +To make the pull request reviewing easier and keep the version tree clean your pull request should consist of a single |
| 186 | +commit. |
| 187 | +It is natural that your branch might contain multiple commits, so you will need to squash these into a single commit. |
| 188 | +Instructions can be |
| 189 | +found [here](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-commits/squashing-commits) |
| 190 | + |
| 191 | +### Improving The Documentation |
| 192 | + |
| 193 | +Please write clear documentation for any new functionality you add. Docstrings will be converted to the API |
| 194 | +documentation, but more human friendly documentation might also be needed. |
| 195 | + |
| 196 | +The documentation is generated using [mkdocs](https://www.mkdocs.org/). To see a preview of any edits you make you can run: |
| 197 | + |
| 198 | +```shell |
| 199 | +hatch run docs |
| 200 | +``` |
| 201 | +and visit the printed address (usually localhost:8080) in your browser |
| 202 | + |
| 203 | +## Attribution |
| 204 | + |
| 205 | +This guide is based on the **contributing.md**. [Make your own](https://contributing.md/)! |
0 commit comments