|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -To run tests locally, please make sure you have [docker](https://www.docker.com/) up and running. |
4 | | -You also need [PHP 8.2](https://www.php.net/) and [composer](https://getcomposer.org/) to be available from your CLI. |
5 | | -Even though we are supporting 3 PHP versions at the time, we are using the lowest supported one for development, currently it's PHP 8.2. |
| 3 | +Below graph explains the process of contributing to Flow. |
6 | 4 |
|
7 | | -## Before you change anything |
| 5 | +```mermaid |
| 6 | +flowchart TD |
| 7 | + subgraph "How to contribute" |
8 | 8 |
|
9 | | -Please make sure that you are aware of our [Architecture Decision Records](/documentation/adrs.md). |
10 | | -It's mandatory to follow all of them without any exceptions unless explicitly overridden by a new ADR. |
11 | | - |
12 | | -## Prepare Project: |
13 | | - |
14 | | -**HEADS UP** - instead of using php installed on your host machine, consider using Nix Shell. |
15 | | -You can find detailed instructions how to use Nix in the [Nix Development Environment](/documentation/contributing/nix.md) section. |
16 | | - |
17 | | -```shell |
18 | | -cp compose.yml.dist compose.yml |
19 | | -composer install |
20 | | -docker compose up -d |
21 | | -``` |
22 | | - |
23 | | -For the code coverage, please install [pcov](https://pecl.php.net/package/pcov). |
24 | | - |
25 | | -Pcov extension is not mandatory, and tests are going to pass without it; however, you won't be able to run mutation tests. |
26 | | - |
27 | | -## Run Test Suite |
28 | | - |
29 | | -```shell |
30 | | -composer test |
31 | | -``` |
32 | | - |
33 | | -Above command will run all tests, including those that require custom extensions. |
34 | | -In case you want to run tests only for a specific part of the project, you can use: |
| 9 | + is-a-bug[Did you found a bug?] |
| 10 | + is-a-bug -->|Yes| can-you-fix-it[Can you fix it?] |
| 11 | + is-a-bug -->|NO| is-a-question[Do you have a question?] |
| 12 | + can-you-fix-it -->|NO| report[Please open a new **Bug Report**] |
| 13 | + can-you-fix-it -->|YES| bug-fix[Please open a pull request with with a fixh] |
35 | 14 |
|
36 | 15 |
|
37 | | -```shell |
38 | | -composer test:core |
39 | | -composer test:lib:doctrine-dbal-bulk |
40 | | -composer test:lib:parquet |
41 | | -composer test:adapter:csv |
42 | | -composer test:bridge:symfony-http-foundation |
43 | | -``` |
44 | | - |
45 | | -## Run Static Analyze |
| 16 | + is-a-question -->|YES| go-to-discord[Ask a **Community Question**] |
| 17 | + is-a-question -->|NO| is-a-proposal[Do you want to propose new feature or a change?] |
46 | 18 |
|
47 | | -```shell |
48 | | -composer static:analyze |
49 | | -``` |
| 19 | + is-a-proposal -->|NO| looking-for-tasks[Are you looking for tasks?] |
50 | 20 |
|
51 | | -**Important** static analyze **MUST** be executed at the lowest supported PHP version |
52 | | -and with dependencies locked by `composer.lock`. |
53 | | -Please make sure to use PHP 8.2 and that you used the `composer install` command first. |
| 21 | + looking-for-tasks -->|YES| check-roadmap[Please check our Roadmap, there is always something to work on] |
54 | 22 |
|
55 | | -## Fixing Coding Standards |
| 23 | + is-a-proposal -->|YES| open-a-proposal[Open a **Proposal**] |
56 | 24 |
|
57 | | -Before committing your code, please make sure that your code is following our coding standards. |
| 25 | + open-a-proposal --> wait-for-proposal-review["Give us time to review your proposal. We should get back to you in the first 24h (usually much faster)"] |
58 | 26 |
|
59 | | -```shell |
60 | | -composer cs:php:fix |
61 | | -``` |
| 27 | + wait-for-proposal-review --> is-proposal-approved[Was your proposal approved by core contributors?] |
62 | 28 |
|
63 | | -This command will automatically fix all coding standards issues in your code. |
64 | | -If you want to first check what needs to be fixed, you can use: |
| 29 | + is-proposal-approved -->|YES| can-you-implement-it[Can you implement it?] |
| 30 | + is-proposal-approved -->|NO| proposal-rejected[Consider implementing that proposal through existing extension points or **Fork this Project**] |
65 | 31 |
|
| 32 | + can-you-implement-it -->|YES| submit-a-pr[Open a **Pull Request**] |
| 33 | + can-you-implement-it -->|No| can-you-sponsor[Can you sponsor that proposal?] |
66 | 34 |
|
67 | | -```shell |
68 | | -composer static:analyze:cs-fixer |
69 | | -composer static:analyze:rector |
| 35 | + can-you-sponsor -->|YES| sponsor-proposal[Awesome! Please mention that in the proposal description.] |
| 36 | + can-you-sponsor -->|NO| wait-for-others[No worries, you will need to wait for someone to implement this one for you.] |
| 37 | + end |
70 | 38 | ``` |
71 | 39 |
|
72 | | -## Test everything |
73 | | - |
74 | | -This command will execute exactly the same tests as we run at GitHub Actions before a PR can get merged. |
75 | | -If it passes locally, you are good to open a pull request. |
| 40 | +## How to? |
76 | 41 |
|
77 | | -```shell |
78 | | -composer build |
79 | | -``` |
| 42 | +- [Submit a Bug Report](https://github.com/flow-php/flow/issues/new?template=bug) |
| 43 | +- [Submit a Proposal](https://github.com/flow-php/flow/issues/new?template=proposal) |
| 44 | +- Ask Community Question |
| 45 | + - [At Flow Discord Server](https://discord.gg/5dNXfQyACW) |
| 46 | + - [At GitHub Discussions](https://github.com/flow-php/flow-php.com/discussions/categories/questions) |
| 47 | +- [Sponsor Project of Proposal](http://flow-php.com/sponsor/) |
| 48 | +- [Project Roadmap](https://github.com/orgs/flow-php/projects/1) |
80 | 49 |
|
81 | | -## Building Documentation |
| 50 | +## Project Roadmap |
82 | 51 |
|
83 | | -Since documentation for DSL and our entire API is automatically generated, you can build it by running: |
| 52 | +> [!IMPORTANT] |
| 53 | +> Flow PHP is managed through [GitHub Projects](https://github.com/orgs/flow-php/projects/1). |
| 54 | +> All code changes **MUST** first be added to the [Roadmap](https://github.com/orgs/flow-php/projects/1). |
| 55 | +> |
| 56 | +> Pull requests without an item in Roadmap might take significantly longer time to review or even get rejected due to missalignment |
| 57 | +> with project architecture or future plans. In order to save time of contributors & maintainers, we would like to review |
| 58 | +> the proposal before anyone starts to code. |
| 59 | +> |
| 60 | +> The only exception from that rule are Bug Fixes - those can be opened without opening a proposal first. |
| 61 | +> However it's still recommened to reach out as sometimes bugs might not be solvable imidiatelly or at all. |
84 | 62 |
|
85 | | -```shell |
86 | | -composer build:docs |
87 | | -composer build:docs:api |
88 | | -``` |
| 63 | +If the idea you are planning to work on is not yet in the [Roadmap](https://github.com/orgs/flow-php/projects/1) |
| 64 | +please create a new [Proposal Issue](https://github.com/flow-php/flow/issues/new?template=PROPOSAL) and wait for further guidance. |
89 | 65 |
|
90 | | -`composer build:docs` must be executed after any adjustments to `functions.php` files (DSL). |
| 66 | +Proposal is considered "Accepted" when added to the Roadmap by one of the Core Contributors. |
| 67 | +By default proposal are added to the upcoming milestone, whatevr can't be delivered during milestone due date is going |
| 68 | +to be moved to the next milestone. |
91 | 69 |
|
92 | | -## Building PHAR |
| 70 | +> Weeks of coding can save you hours of planning. |
93 | 71 |
|
94 | | -```shell |
95 | | -composer build:phar |
96 | | -./build/flow.phar --version |
97 | | -``` |
| 72 | +Opening a pull request without reaching out first might get rejected and eventually closed. |
98 | 73 |
|
99 | | -## Building Docker Image |
| 74 | +**🐛 Bug Fixes** - bug fixes are the only exception from the above rule. Bug Fixes can be opened directly without |
100 | 75 |
|
101 | | -In order to build docker image and load it to local registry please use: |
| 76 | +## Before you start coding |
102 | 77 |
|
103 | | -```shell |
104 | | -docker buildx build -t flow-php/flow:latest . --progress=plain --load |
105 | | -``` |
| 78 | +Please make sure that you are aware of our [Architecture Decision Records](/documentation/adrs.md). |
| 79 | +It's mandatory to follow all of them without any exceptions unless explicitly overridden by a new ADR. |
106 | 80 |
|
107 | | -Usage: |
| 81 | +## Next Steps |
108 | 82 |
|
109 | | -```shell |
110 | | -docker run -v $(pwd):/flow-workspace -it flow-php/flow:latest --version |
111 | | -``` |
| 83 | +- [Setup development environment](/documentation/contributing/environment.md) |
| 84 | + - [Nix Shell](/documentation/contributing/nix.md) |
| 85 | +- [Development Guidelines](/documentation/contributing/guidelines.md) |
0 commit comments