Skip to content

Commit 6d96f1b

Browse files
lotyplotyp
committed
docs: updating contributing guide
1 parent c8d89f0 commit 6d96f1b

File tree

8 files changed

+336
-14
lines changed

8 files changed

+336
-14
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Contributing
2+
3+
If you would like to contribute to this project, please open an issue or a pull request. We are always looking for ways to improve the project and would love to hear your ideas.
4+
5+
The latest changes are always in master branch, so please make your Pull Request against that branch.
6+
7+
<br>
8+
9+
## 🚩 Development Requirements
10+
11+
To set up your local development environment, you'll need the following:
12+
13+
- **Operating System**: macOS Monterey+ or Linux.
14+
15+
- Docker Version 26.0.0 or newer. Installation guides:
16+
17+
- [Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
18+
- [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)
19+
20+
- **Homebrew** (macOS only): Install via [brew.sh](https://brew.sh/).
21+
22+
- [Pre-commit](https://pre-commit.com)
23+
24+
(Optional): Automates the running of git pre-commit hooks.
25+
26+
- Installation: `brew install pre-commit`
27+
28+
- [Commitizen](https://commitizen-tools.github.io/commitizen/#macos)
29+
30+
(Optional): Assists in formatting git commits.
31+
32+
- Installation: `brew install commitizen`
33+
34+
<br>
35+
36+
## 🛠️ Makefile
37+
38+
This project uses a Makefile to streamline common development tasks. The Makefile includes utilities for managing Docker environments, running tests, and linting code.
39+
40+
```bash
41+
$ make help
42+
```
43+
44+
![Screenshot](../assets/screenshot.png)
45+
46+
### → Key Commands
47+
48+
- `make up`: Starts all services using Docker Compose.
49+
- `make down`: Stops all running Docker containers.
50+
- `make ssh`: Logs into the running application container for command line operations.
51+
- `make lint`: Executes all linting procedures for YAML, PHP, and Composer files.
52+
- `make test`: Runs all configured tests using PHPUnit and Pest.
53+
- `make commit`: Runs Commitizen for commit message formatting in a Docker environment.
54+
- `make install`: Installs project dependencies through Composer in a Dockerized environment.
55+
56+
Refer to the output of `make help` for a comprehensive list of available commands.
57+
58+
<br>
59+
60+
## 💻 Workflow
61+
62+
> [!IMPORTANT]
63+
>
64+
> Please feature/fix/update... into individual PRs (not one changing everything)
65+
66+
- **Fork the Repository**: Start by forking the repository to your GitHub account.
67+
- **Create a Branch**: In your fork, create a new branch for your work. Name it appropriately based on the feature, fix, or update you're working on.
68+
- **Make Your Changes**: Implement your changes, commit them, and push the branch to your fork.
69+
- **Open a Pull Request**: Submit a pull request to the `master` branch of the original repository. Ensure your PR is focused, addressing a single feature, fix, or improvement.
70+
71+
<br>
72+
73+
## 🐳 Docker Support
74+
75+
This package leverages Docker to provide a consistent and isolated development environment. The included [`Makefile`](../Makefile) utilizes `docker-compose.yaml` along with the [wayofdev/docker-php-dev](https://github.com/wayofdev/docker-php-dev) PHP image to streamline setup and usage. This setup facilitates easy configuration of tools like Xdebug for debugging and profiling, enhancing the development experience.
76+
77+
To run docker container:
78+
79+
```bash
80+
$ make up
81+
```
82+
83+
Other commands:
84+
85+
```bash
86+
# Login inside container
87+
$ make ssh
88+
89+
# Turn off containers
90+
$ make down
91+
```
92+
93+
<br>
94+
95+
## ⚡️ Continuous Integration with GitHub Actions
96+
97+
Our project employs [GitHub Actions](https://github.com/features/actions) for continuous integration, ensuring code quality and reliability. We encourage contributors to review our workflow configurations to understand the CI processes:
98+
99+
- [`workflows/integrate.yaml`](workflows/integrate.yaml)
100+
- [`workflows/apply-labels.yml`](workflows/apply-labels.yml)
101+
- [`workflows/create-release.yml`](workflows/create-release.yml)
102+
- [`workflows/shellcheck.yml`](workflows/shellcheck.yml)
103+
- [`workflows/create-arch-diagram.yml`](workflows/create-arch-diagram.yml)
104+
105+
<br>
106+
107+
## 📝 Before You Contribute
108+
109+
- **Tests**: Include tests that cover any new features or bug fixes.
110+
- **Code Quality**: Utilize `make lint` for code style checks and `make lint-stan` for static analysis with [Psalm](https://psalm.dev/).
111+
- **Documentation**: Update relevant documentation to reflect your changes, ensuring other developers can understand and use your contributions effectively.
112+
113+
<br>
114+
115+
## ✉️ Commit Message Guidelines
116+
117+
We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard. Please structure your commit messages as follows, using the appropriate prefix:
118+
119+
**Examples:**
120+
121+
```bash
122+
$ git commit -am 'feat: some feature was introduced'
123+
$ git commit -am 'fix: something has been fixed'
124+
```
125+
126+
**Allowed Prefixes:**
127+
128+
| Prefix | Purpose |
129+
| ---------- | ------------------------------------------------------------ |
130+
| `feat` | Introduces a new feature |
131+
| `fix` | Fixes a bug |
132+
| `perf` | Improves performance |
133+
| `docs` | Documentation only changes |
134+
| `style` | Code style changes (formatting, missing semi-colons, etc.) |
135+
| `deps` | Updates dependencies |
136+
| `refactor` | Code changes that neither fixes a bug nor adds a feature |
137+
| `ci` | Changes to our CI configuration files and scripts |
138+
| `test` | Adding missing tests or correcting existing tests |
139+
| `revert` | Reverts a previous commit |
140+
| `build` | Changes that affect the build system or external dependencies |
141+
| `chore` | Other changes that don't modify src or test files |
142+
| `security` | A code change that fixes a security issue |
143+
144+
<br>
145+
146+
## 🔍 Coding Standards and Tools
147+
148+
We enforce coding standards to maintain high code quality and readability. Here's a list of tools we use:
149+
150+
### → Composer Normalization
151+
152+
We use [`ergebnis/composer-normalize`](https://github.com/ergebnis/composer-normalize) to normalize `composer.json`.
153+
154+
Use:
155+
156+
```bash
157+
$ make lint-composer
158+
```
159+
160+
### → Yaml Lint
161+
162+
We use [`yamllint`](https://github.com/adrienverge/yamllint) to enforce coding standards in YAML files.
163+
164+
If you do not have `yamllint` installed yet, run
165+
166+
```bash
167+
$ brew install yamllint
168+
```
169+
170+
to install `yamllint`.
171+
172+
To lint yaml files run:
173+
174+
```bash
175+
$ make lint-yaml
176+
```
177+
178+
### → PHP CS Fixer
179+
180+
We use [`friendsofphp/php-cs-fixer`](https://github.com/FriendsOfPHP/PHP-CS-Fixer) together with [`wayofdev/php-cs-fixer-config`](https://github.com/wayofdev/php-cs-fixer-config) to enforce coding standards in PHP files.
181+
182+
Run
183+
184+
```bash
185+
$ make lint-php
186+
```
187+
188+
to automatically fix coding standard violations.
189+
190+
<br>
191+
192+
## 🔬 Dependency Analysis
193+
194+
We use [`maglnet/composer-require-checker`](https://github.com/maglnet/ComposerRequireChecker) to prevent the use of unknown symbols in production code.
195+
196+
Run
197+
198+
```sh
199+
make lint-deps
200+
```
201+
202+
to run a dependency analysis.
203+
204+
<br>
205+
206+
## 🦠 Mutation Tests
207+
208+
We use [`infection/infection`](https://github.com/infection/infection) to ensure a minimum quality of the tests.
209+
210+
Xdebug support is enabled by default, when running commands through `Makefile`:
211+
212+
```sh
213+
make infect
214+
```
215+
216+
to run mutation tests.
217+
218+
<br>
219+
220+
## ⚙️ Static Code Analysis
221+
222+
We use [`phpstan/phpstan`](https://github.com/phpstan/phpstan) to statically analyze the code.
223+
224+
Run
225+
226+
```sh
227+
make lint-stan
228+
```
229+
230+
to run a static code analysis.
231+
232+
We also use the baseline features of [`phpstan/phpstan`](https://phpstan.org/user-guide/baseline).
233+
234+
Run
235+
236+
```sh
237+
make lint-stan-baseline
238+
```
239+
240+
to regenerate the baselines in [`../phpstan-baseline.neon`](../phpstan-baseline.neon).
241+
242+
> [!IMPORTANT]
243+
>
244+
> Ideally, the baseline file should stay empty or shrink over time.
245+
246+
<br>
247+
248+
## 🧪 Tests
249+
250+
We use [`phpunit/phpunit`](https://github.com/sebastianbergmann/phpunit) and [`pestphp/pest`](https://github.com/pestphp/pest) to drive the development.
251+
252+
Run
253+
254+
```sh
255+
make tests
256+
```
257+
258+
to run all the tests.
259+
260+
<br>
261+
262+
## 📦 Pre-commit Hooks
263+
264+
Pre-commit hooks are an optional but highly recommended way to automate the linting and quality checks before committing changes to the repository. This project provides a predefined configuration that helps in maintaining code quality and consistency.
265+
266+
### → Configured Hooks
267+
268+
Our pre-commit configuration includes several hooks:
269+
270+
- **Trailing Whitespace**: Removes unnecessary trailing spaces.
271+
- **End-of-File Fixer**: Ensures that files end with a newline.
272+
- **Check Added Large Files**: Prevents accidentally adding large files to the git repository, with a current limit set to 600 KB.
273+
- **Commitizen**: Ensures commit messages meet the conventional commit format. This hook is triggered at the commit message stage.
274+
- **PHP-CS-Fixer:** Enforces coding standards in PHP files.
275+
276+
### → Installing Pre-commit Hooks
277+
278+
To utilize these hooks, you first need to install them using the command provided by the Makefile:
279+
280+
```bash
281+
$ make hooks
282+
```

‎.pre-commit-config.yaml

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,32 @@
22

33
repos:
44
- repo: https://github.com/pre-commit/pre-commit-hooks
5-
rev: v4.5.0
5+
rev: v4.6.0
66
hooks:
77
- id: trailing-whitespace
88
- id: end-of-file-fixer
99
- id: check-added-large-files
1010
args: ['--maxkb=600']
11-
- id: fix-encoding-pragma
1211

1312
- repo: https://github.com/commitizen-tools/commitizen
14-
rev: v3.13.0
13+
rev: v3.21.3
1514
hooks:
1615
- id: commitizen
1716
stages:
1817
- commit-msg
1918

19+
- repo: local
20+
hooks:
21+
- id: php-cs-fixer
22+
name: PHP CS Fixer
23+
description: Lint files using PHP CS Fixer
24+
entry: vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php --verbose --diff
25+
language: system
26+
types: [php]
27+
exclude: ^vendor/
28+
files: \.php$
29+
pass_filenames: false
30+
require_serial: true
31+
always_run: true
32+
2033
...

0 commit comments

Comments
 (0)