Skip to content

Commit f7f1675

Browse files
paduszykpaduszyk
committed
docs: extend README and add contributing guide
1 parent a9d1bb4 commit f7f1675

File tree

3 files changed

+649
-0
lines changed

3 files changed

+649
-0
lines changed

‎docs/CODE_OF_CONDUCT.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our community
6+
a harassment-free experience for everyone, regardless of age, body size, visible
7+
or invisible disability, ethnicity, sex characteristics, gender identity and expression,
8+
level of experience, education, socio-economic status, nationality, personal appearance,
9+
race, religion, or sexual identity and orientation.
10+
11+
We pledge to act and interact in ways that contribute to an open, welcoming, diverse,
12+
inclusive, and healthy community.
13+
14+
## Our Standards
15+
16+
Examples of behavior that contributes to a positive environment for our community
17+
include:
18+
19+
- Demonstrating empathy and kindness toward other people
20+
- Being respectful of differing opinions, viewpoints, and experiences
21+
- Giving and gracefully accepting constructive feedback
22+
- Accepting responsibility and apologizing to those affected by our mistakes, and
23+
learning from the experience
24+
- Focusing on what is best not just for us as individuals, but for the overall community
25+
26+
Examples of unacceptable behavior include:
27+
28+
- The use of sexualized language or imagery, and sexual attention or advances of
29+
any kind
30+
- Trolling, insulting or derogatory comments, and personal or political attacks
31+
- Public or private harassment
32+
- Publishing others' private information, such as a physical or email
33+
- Other conduct which could reasonably be considered inappropriate in a professional
34+
setting
35+
36+
## Enforcement Responsibilities
37+
38+
Community leaders are responsible for clarifying and enforcing our standards of
39+
acceptable behavior and will take appropriate and fair corrective action in response
40+
to any behavior that they deem inappropriate, threatening, offensive, or harmful.
41+
42+
Community leaders have the right and responsibility to remove, edit, or reject comments,
43+
commits, code, wiki edits, issues, and other contributions that are not aligned
44+
to this Code of Conduct, and will communicate reasons for moderation decisions when
45+
appropriate.
46+
47+
## Scope
48+
49+
This Code of Conduct applies within all community spaces, and also applies when
50+
an individual is officially representing the community in public spaces. Examples
51+
of representing our community include using an official e-mail address, posting
52+
via an official social media account, or acting as an appointed representative at
53+
an online or offline event.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported
58+
to the community leaders responsible for enforcement using any of the
59+
[reporting services][github-reporting-services] provided by GitHub. All complaints
60+
will be reviewed and investigated promptly and fairly. All community leaders are
61+
obligated to respect the privacy and security of the reporter of any incident.
62+
63+
## Enforcement Guidelines
64+
65+
Community leaders will follow these Community Impact Guidelines in determining the
66+
consequences for any action they deem in violation of this Code of Conduct:
67+
68+
### 1. Correction
69+
70+
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional
71+
or unwelcome in the community.
72+
73+
**Consequence**: A private, written warning from community leaders, providing clarity
74+
around the nature of the violation and an explanation of why the behavior was inappropriate.
75+
A public apology may be requested.
76+
77+
### 2. Warning
78+
79+
**Community Impact**: A violation through a single incident or series of actions.
80+
81+
**Consequence**: A warning with consequences for continued behavior. No interaction
82+
with the people involved, including unsolicited interaction with those enforcing
83+
the Code of Conduct, for a specified period of time. This includes avoiding interactions
84+
in community spaces as well as external channels like social media. Violating these
85+
terms may lead to a temporary or permanent ban.
86+
87+
### 3. Temporary Ban
88+
89+
**Community Impact**: A serious violation of community standards, including sustained
90+
inappropriate behavior.
91+
92+
**Consequence**: A temporary ban from any sort of interaction or public communication
93+
with the community for a specified period of time. No public or private interaction
94+
with the people involved, including unsolicited interaction with those enforcing
95+
the Code of Conduct, is allowed during this period. Violating these terms may lead
96+
to a permanent ban.
97+
98+
### 4. Permanent Ban
99+
100+
**Community Impact**: Demonstrating a pattern of violation of community standards,
101+
including sustained inappropriate behavior, harassment of an individual, or aggression
102+
toward or disparagement of classes of individuals.
103+
104+
**Consequence**: A permanent ban from any sort of public interaction within the
105+
community.
106+
107+
## Attribution
108+
109+
This Code of Conduct is adapted from the [Contributor Covenant][covenant], version
110+
2.0, available [here][covenant-cc]. Community Impact Guidelines were inspired by
111+
[Mozilla's code of conduct enforcement ladder][mozilla-cc]. For answers to common
112+
questions about this code of conduct, see the [FAQ][covenant-faq]. Translations
113+
are available [here][covenant-translations].
114+
115+
[covenant]: https://www.contributor-covenant.org
116+
[covenant-cc]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
117+
[covenant-faq]: https://www.contributor-covenant.org/faq
118+
[covenant-translations]: https://www.contributor-covenant.org/translations
119+
[github-reporting-services]: https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam
120+
[mozilla-cc]: https://github.com/mozilla/diversity

‎docs/CONTRIBUTING.md

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# Contributing Guide
2+
3+
> **New to Open Source Contributions?**
4+
>
5+
> If this is your first time contributing to an open-source project, we highly recommend
6+
> reviewing the official [GitHub documentation][github-documentation] or other relevant
7+
> resources, such as [First Contributions][first-contributions].
8+
9+
We welcome contributions of all types. Whether you are a beginner or an experienced
10+
developer, you can get involved by:
11+
12+
- opening issues;
13+
- submitting pull requests (PRs);
14+
- participating in discussions on existing issues and PRs.
15+
16+
When opening an issue or a PR, please use our forms and templates to adhere to the
17+
provided guidelines and checklists.
18+
19+
## Issues
20+
21+
We welcome the submission of various types of issues, including:
22+
23+
- bug reports;
24+
- feature requests;
25+
- documentation updates;
26+
- code refactoring and performance improvements.
27+
28+
Please use the specific [form][open-issue] corresponding to each issue type. If
29+
your issue does not match any of the categories above, start with a blank template.
30+
31+
> Regardless of the issue type, you will be asked to confirm that you are familiar
32+
> with this guide and the project's [Code of Conduct](#code-of-conduct), and to
33+
> check that the issue is not a duplicate.
34+
35+
## Pull Requests
36+
37+
### Guidelines for Submitting PRs
38+
39+
To improve the chances of your PR being accepted, please adhere to the following
40+
guidelines:
41+
42+
- **Atomic Changes**: Keep your PR focused on a single change or feature to make
43+
reviewing easier.
44+
45+
- **Local Validation**: After submission, the CI system will automatically test
46+
the package and run all necessary checks. However, it is strongly recommended
47+
to run all tests and Pre-commit checks locally to catch any issues before submitting
48+
a PR.
49+
50+
> For more information, see [Nox](#nox) and [Pre-commit](#pre-commit).
51+
52+
- **Test Coverage and Documentation**: Ensure that your changes are thoroughly tested
53+
and update the documentation where applicable. The project aims for 100% test
54+
coverage, and we expect the same from all submitted PRs.
55+
56+
> PRs lacking relevant tests will not be considered for merging.
57+
58+
- **PR Title**: PR titles must follow the [Conventional Commits][conventional-commits]
59+
specification and use standard commit [types][conventional-commit-types].
60+
61+
- **Commit Messages**: While commit messages are not strictly validated, it is recommended
62+
to provide a single commit per PR with a message that matches the PR title, in
63+
line with the "atomicity" principle.
64+
65+
- **Merging Strategy**: This project uses the "Squash and Merge" strategy for PRs.
66+
67+
> Unlike most open-source projects on GitHub, we do not append the PR number to
68+
> the squashed commit message.
69+
70+
### Environment Setup
71+
72+
To contribute via a pull request, follow these steps to set up the development environment,
73+
either [locally](#local-development) or through a [Dev Container](#development-in-a-dev-container).
74+
The Dev Container option is strongly recommended as it ensures a consistent development
75+
environment across all contributors.
76+
77+
#### Local Development
78+
79+
1. Fork the repository, clone it to your local machine, and navigate to the project's
80+
root directory.
81+
82+
2. Install Node packages:
83+
84+
```console
85+
npm ci
86+
```
87+
88+
> Ensure that Node.js is installed. If not, [download][node.js] and install the
89+
> latest release.
90+
91+
3. Install [`pyenv`][pyenv] and [`pyenv-virtualenv`][pyenv-virtualenv].
92+
93+
4. Install the necessary Python versions, as specified in [`pyproject.toml`][pyproject.toml]:
94+
95+
```console
96+
pyenv install <VERSION>
97+
```
98+
99+
5. Create and activate a virtual environment:
100+
101+
```console
102+
pyenv virtualenv venv && pyenv activate venv
103+
```
104+
105+
6. Install the package in development mode:
106+
107+
```console
108+
pip install -e ".[dev]"
109+
```
110+
111+
7. Install the [Pre-commit][pre-commit] hooks:
112+
113+
```console
114+
pre-commit install --install-hooks
115+
```
116+
117+
Once the setup is complete, you can run [Nox][nox] to ensure everything works:
118+
119+
```console
120+
nox
121+
```
122+
123+
> For more details, refer to the [Nox](#nox) section.
124+
125+
#### Development in a Dev Container
126+
127+
1. Ensure [Docker][docker] is installed on your machine.
128+
129+
2. Open the project in an Integrated Development Environment (IDE) that supports
130+
[Dev Containers][dev-containers].
131+
132+
3. Reopen the project inside the Dev Container when prompted.
133+
134+
This setup will install everything you need automatically, following the steps in
135+
[Local Development](#local-development).
136+
137+
> For more details, please refer to the official Development Containers [documentation][dev-containers]
138+
> and the project's Dev Container [configuration][devcontainer.json].
139+
140+
**Using Visual Studio Code?**
141+
142+
[![Open in VS Code](https://img.shields.io/badge/Dev_Container-open_in_VS_Code-007acc)][open-in-vs-code]
143+
144+
If so, click the badge above to get started!
145+
146+
## Nox
147+
148+
The project uses [Nox][nox] to build, lint, format, and type-check the package,
149+
as well as to run tests across various Python and Django environments and measure
150+
test coverage.
151+
152+
To list all available Nox sessions, run:
153+
154+
```console
155+
nox -l
156+
```
157+
158+
To perform a complete check, run:
159+
160+
```console
161+
nox
162+
```
163+
164+
> For more information, refer to the project's [`noxfile.py`][noxfile.py] and/or
165+
> consult the Nox [documentation][nox].
166+
167+
### Coding Style
168+
169+
To check the Python code quality, format and type annotations, run the sessions
170+
tagged with `lint`:
171+
172+
```console
173+
nox -t lint
174+
```
175+
176+
This will run the [`ruff`][ruff]'s linter and formatter and [`mypy`][mypy] to perform
177+
a strict type-check.
178+
179+
### Tests
180+
181+
The package can be thoroughly tested by running the sessions tagged with `test`:
182+
183+
```console
184+
nox -t test
185+
```
186+
187+
This command will discover and run (via [`pytest`][pytest]) all tests across various
188+
Python and Django environments and measure test coverage.
189+
190+
For quicker runs, you can test the package by running `pytest` directly:
191+
192+
```console
193+
pytest
194+
```
195+
196+
However, this only tests against versions of Python and Django that are pinned to
197+
the active virtual environment. If your PR introduces changes that might affect
198+
compatibility with older Python versions, remember to run the full test suite via
199+
Nox sessions.
200+
201+
## Pre-commit
202+
203+
The project uses [Pre-commit][pre-commit] to ensure consistent quality and formatting
204+
across the entire project.
205+
206+
In addition to the tools mentioned in the [Coding Style](#coding-style) section,
207+
we use the following extra tools for assets not being a part of the source code:
208+
209+
- [`prettier`][prettier] for auto-formatting non-Python files;
210+
- [`markdownlint-cli2`][markdownlint-cli2] for linting documentation files.
211+
212+
Pre-commit runs automatically on each commit, but to check everything before committing,
213+
run:
214+
215+
```console
216+
pre-commit run -a
217+
```
218+
219+
> For more information, see the project's [`.pre-commit-config.yaml`][pre-commit-config]
220+
> and the Pre-commit [documentation][pre-commit].
221+
222+
The mentioned tools can also be executed individually via `npx`:
223+
224+
```console
225+
npx prettier --check .
226+
npx markdownlint-cli2
227+
```
228+
229+
## Code of Conduct
230+
231+
Please review and adhere to our [Code of Conduct][code-of-conduct].
232+
233+
We are committed to creating a welcoming and inclusive environment for all contributors.
234+
235+
## Thank You! <!-- markdownlint-disable-line -->
236+
237+
No contribution is too small &mdash; every bit helps! Together, we can build something
238+
amazing.
239+
240+
Thank you for making this project better and for being a part of our open-source
241+
community!
242+
243+
[code-of-conduct]: https://github.com/paduszyk/django-management-commands/blob/main/docs/CODE_OF_CONDUCT.md
244+
[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/
245+
[conventional-commit-types]: https://github.com/commitizen/conventional-commit-types/blob/master/index.json
246+
[dev-containers]: https://containers.dev
247+
[devcontainer.json]: https://github.com/paduszyk/django-management-commands/blob/main/.devcontainer/devcontainer.json
248+
[docker]: https://www.docker.com
249+
[first-contributions]: https://github.com/firstcontributions/first-contributions
250+
[github-documentation]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
251+
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
252+
[mypy]: https://mypy.readthedocs.io/en/stable/
253+
[node.js]: https://nodejs.org/
254+
[nox]: https://github.com/wntrblm/nox
255+
[noxfile.py]: https://github.com/paduszyk/django-management-commands/blob/main/noxfile.py
256+
[open-in-vs-code]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/paduszyk/django-management-commands
257+
[open-issue]: https://github.com/paduszyk/django-management-commands/issues/new/choose
258+
[pre-commit]: https://pre-commit.com
259+
[pre-commit-config]: https://github.com/paduszyk/django-management-commands/blob/main/.pre-commit-config.yaml
260+
[prettier]: https://prettier.io
261+
[pyenv-virtualenv]: https://github.com/pyenv/pyenv-virtualenv
262+
[pyenv]: https://github.com/pyenv/pyenv
263+
[pyproject.toml]: https://github.com/paduszyk/django-management-commands/blob/main/pyproject.toml
264+
[pytest]: https://docs.pytest.org/
265+
[ruff]: https://docs.astral.sh/ruff/

0 commit comments

Comments
 (0)