11# Contribution guide
22
3- Thanks for considering contributing to this project! Each contribution is
4- highly appreciated. In order to maintain a high code quality, please follow
5- all steps below.
3+ Thanks for considering contributing to this project. Contributions of any size are highly appreciated.
4+
5+ To keep the code base consistent and maintainable, please follow the workflow described below before
6+ submitting a pull request.
67
78## Requirements
89
910- PHP >= 8.2
10- - Docker (when running E2E tests)
11- - GPG (when running E2E tests)
12- - [ ` jq ` ] ( https://github.com/jqlang/jq ) (when running E2E tests)
11+ - Composer
12+ - Docker (for E2E tests)
13+ - GPG (for E2E tests)
14+ - [ ` jq ` ] ( https://github.com/jqlang/jq ) (for E2E tests)
1315
1416## Preparation
1517
@@ -22,81 +24,96 @@ cd cache-warmup
2224composer install
2325```
2426
25- ## Run code analyzers
27+ ## Development workflow
2628
27- ``` bash
28- # All analyzers
29- composer analyze
29+ A typical contribution workflow looks like this:
3030
31- # Specific analyzers
32- composer analyze:dependencies
33- ```
31+ 1 . Apply automatic fixes.
32+ 2 . Run all checks.
33+ 3 . Run the test suite.
34+ 4 . Submit a pull request.
3435
35- ## Run linters
36+ ### Apply automatic fixes
3637
37- ``` bash
38- # All linters
39- composer lint
38+ Use the following commands to normalize and format the code base:
4039
41- # Specific linters
42- composer lint:composer
43- composer lint:editorconfig
44- composer lint:php
45-
46- # Fix all CGL issues
40+ ``` bash
41+ # Apply all automatic fixes
4742composer fix
4843
49- # Fix specific CGL issues
44+ # Apply specific fixes
5045composer fix:composer
5146composer fix:editorconfig
5247composer fix:php
5348```
5449
55- ## Run static code analysis
50+ ### Run checks
51+
52+ Use ` composer check ` to run the full code quality pipeline locally. This command bundles dependency analysis,
53+ static analysis, coding style checks, and Rector in dry-run mode so that potential refactorings can be reviewed
54+ without changing files.
5655
5756``` bash
58- # All static code analyzers
59- composer sca
57+ # Run all checks
58+ composer check
59+
60+ # Run specific checks
61+ composer check:deps
62+ composer check:refactor
63+ composer check:static
64+ composer check:style
65+
66+ # Run specific style checks
67+ composer check:style:composer
68+ composer check:style:editorconfig
69+ composer check:style:php
70+ ```
71+
72+ ### Run refactorings
73+
74+ Refactorings are intentionally separated from regular checks because they may change the code base.
6075
61- # Specific static code analyzers
62- composer sca:php
76+ ``` bash
77+ # Run all configured refactorings
78+ composer refactor
79+
80+ # Run specific refactorings
81+ composer refactor:php
6382```
6483
65- ## Run tests
84+ ### Run tests
85+
86+ Run the full test suite before opening a pull request:
6687
6788``` bash
68- # All tests
89+ # Run all tests
6990composer test
7091
71- # E2E tests
92+ # Run E2E tests
7293composer test:e2e
7394composer test:e2e:docker
7495composer test:e2e:phar
7596
76- # Unit tests
97+ # Run unit tests
7798composer test:unit
7899
79- # Unit tests with code coverage
100+ # Run unit tests with code coverage
80101composer test:unit:coverage
81102```
82103
83- ### Test reports
104+ ## Coverage reports
84105
85- Code coverage reports are written to ` .build/coverage ` . You can open the
86- last HTML report like follows:
106+ Code coverage reports are written to ` .build/coverage ` . Open the latest HTML report with:
87107
88108``` bash
89109open .build/coverage/html/index.html
90110```
91111
92- ## Submit a pull request
112+ ## Pull requests
93113
94- Once you have finished your work, please
95- [ ** submit a pull request** ] ( https://github.com/eliashaeussler/cache-warmup/compare )
96- and describe what you've done. Ideally, your PR references an issue describing
97- the problem you're trying to solve.
114+ Once the changes are ready, please [ submit a pull request] ( https://github.com/eliashaeussler/cache-warmup/compare )
115+ and describe what was changed and why. Ideally, the pull request references an issue that describes the
116+ problem being solved.
98117
99- All described code quality tools are automatically executed on each pull request
100- for all currently supported PHP versions. Take a look at the appropriate
101- [ workflows] ( ../.github/workflows )
102- to get a detailed overview.
118+ All documented code quality tools are executed automatically for pull requests across the currently
119+ supported PHP versions. For details, refer to the [ GitHub Actions workflows] ( ../.github/workflows ) .
0 commit comments