Debian Codegraph @

vendor/zircote/swagger-php/CONTRIBUTING.md

raw
1 ## Contributing
2
3 Contributions of any kind are welcome.
4
5 Feel free to submit [Github Issues](https://github.com/zircote/swagger-php/issues)
6 or [pull requests](https://github.com/zircote/swagger-php/pulls).
7
8
9 ## Quick Guide
10
11 The documentation site has [some details](https://zircote.github.io/swagger-php/guide/under-the-hood.html#documentation) about internals.
12
13 ### How-To
14
15 * [Fork](https://help.github.com/articles/fork-a-repo/) the repo.
16 * [Checkout](https://git-scm.com/docs/git-checkout) the branch you want to make changes on.
17 * Typically, this will be `master`. Note that most of the time, `master` represents the next release of swagger-php, so Pull Requests that break backwards compatibility might be postponed.
18 * Install dependencies: `composer install`.
19 * Create a new branch, e.g. `feature-foo` or `bugfix-bar`.
20 * Make changes.
21 * If you are adding functionality or fixing a bug - add a test!
22
23 Prefer adding new test cases over modifying existing ones.
24 * Update documentation: `composer docs:gen`.
25 * Run static analysis using PHPStan/Psalm: `composer analyse`.
26 * Check if tests pass: `composer test`.
27 * Fix code style issues: `composer cs`.
28
29
30 ## Documentation
31
32 The documentation website is build from the [docs](docs/) folder with [vitepress](https://vitepress.vuejs.org).
33 This process involves converting the existing markdown (`.md`) files into static HTML pages and publishing them.
34
35 Some reference content is based on the existing code, so changes to annotations, attributes and processors will require to re-generate those markdown files: `composer docs:gen`.
36
37 The actual published content is managed in the [gh-pages](https://github.com/zircote/swagger-php/tree/gh-pages) branch and driven by a [publish action](https://github.com/zircote/swagger-php/actions/workflows/gh-pages.yml).
38
39
40 ## Useful commands
41
42 ### To run both unit tests and linting execute
43 ```shell
44 composer test
45 ```
46
47 ### To run static-analysis execute
48 ```shell
49 composer analyse
50 ```
51
52 ### Running unit tests only
53 ```shell
54 ./bin/phpunit
55 ```
56
57 ### Regenerate reference markup docs
58 ```shell
59 composer docs:gen
60 ```
61
62 ### Running linting only
63 ```shell
64 composer lint
65 ```
66
67 ### To make `php-cs-fixer` fix linting errors
68 ```shell
69 composer cs
70 ```
71
72 ### Run dev server for local development of `gh-pages`
73 ```shell
74 composer docs:dev
75 ```
76
77
78 ## Project's Standards
79
80 * [PSR-1: Basic Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
81 * [PSR-2: Coding Style Guide](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
82 * [PSR-4: Autoloading Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md)
83 * [PSR-5: PHPDoc (draft)](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md)