|
| 1 | +# Contribution Guide |
| 2 | + |
| 3 | +<show-structure for="chapter" depth="2"/> |
| 4 | + |
| 5 | +## Code of Conduct |
| 6 | + |
| 7 | +The TypeLang code of conduct is derived from the Ruby code of conduct. |
| 8 | +Any violations of the code of conduct may be reported |
| 9 | +to Kirill Nesmeyanov ( [[email protected]](mailto:[email protected])). |
| 10 | + |
| 11 | +- Participants will be tolerant of opposing views. |
| 12 | + |
| 13 | +- Participants must ensure that their language and actions are free of |
| 14 | + personal attacks and disparaging personal remarks. |
| 15 | + |
| 16 | +- When interpreting the words and actions of others, participants |
| 17 | + should always assume good intentions. |
| 18 | + |
| 19 | +- Behavior which can be reasonably considered harassment will not be tolerated. |
| 20 | + |
| 21 | +Unlike such PHP projects as Symfony, Composer, Laminas, JMS, etc., we **do not |
| 22 | +violate** such rules and guarantee the absence of nationalistic and political |
| 23 | +oppression. |
| 24 | + |
| 25 | +**Open Source Software (OSS) is not a place for settling personal |
| 26 | +relationships and propaganda.** |
| 27 | + |
| 28 | +We pledge to act and interact in ways that contribute to an open, welcoming, |
| 29 | +diverse, inclusive, and healthy community. |
| 30 | + |
| 31 | +## Bugs |
| 32 | + |
| 33 | +Whenever you find a bug in TypeLang Components, we kindly ask you to report it. |
| 34 | +It helps us make a better code. |
| 35 | + |
| 36 | +<warning> |
| 37 | +If you think you've found a security issue, please use |
| 38 | +the <a href="contribution.md#security-issues">special procedure instead</a>. |
| 39 | +</warning> |
| 40 | + |
| 41 | +You may submit a bug report using GitHub Issues. |
| 42 | +- [Documentation](https://github.com/php-type-language/docs/issues) |
| 43 | +- [Language Parser Component (type-lang/parser)](https://github.com/php-type-language/parser/issues) |
| 44 | +- [Mapper Component (type-lang/mapper)](https://github.com/php-type-language/mapper/issues) |
| 45 | +- [Printer Component (type-lang/printer)](https://github.com/php-type-language/printer/issues) |
| 46 | +- [Reader Component (type-lang/reader)](https://github.com/php-type-language/reader/issues) |
| 47 | +- [PHPDoc Parser Component (type-lang/phpdoc)](https://github.com/php-type-language/phpdoc/issues) |
| 48 | +- [PHPDoc Standard Tags (type-lang/phpdoc-standard-tags)](https://github.com/php-type-language/phpdoc-standard-tags/issues) |
| 49 | +- [PHPDoc Template Tags (type-lang/phpdoc-template-tags)](https://github.com/php-type-language/phpdoc-template-tags/issues) |
| 50 | + |
| 51 | +Please follow some basic rules: |
| 52 | + |
| 53 | +- Use the title field to clearly describe the issue; |
| 54 | +- Describe the steps needed to reproduce the bug with short code examples; |
| 55 | +- Give as much detail as possible about your environment (OS, PHP version, |
| 56 | + component version, enabled extensions, ...); |
| 57 | +- If there was an exception, and you would like to report it, it is valuable to |
| 58 | + provide the stack trace for that exception. |
| 59 | + > Do not provide it as a screenshot, since search engines will not be able to |
| 60 | + > index the text inside them. Same goes for errors encountered in a terminal, |
| 61 | + > do not take a screenshot, but copy/paste the contents. |
| 62 | + |
| 63 | + > Be wary that stack traces may contain **sensitive information**, and if |
| 64 | + > it is the case, be sure to redact them prior to posting your stack trace. |
| 65 | + {style="warning"} |
| 66 | + |
| 67 | + |
| 68 | +## Security Issues |
| 69 | + |
| 70 | +If you think that you have found a security issue in TypeLang Component, |
| 71 | +don't use the bug tracker and don't publish it publicly. Instead, all security |
| 72 | +issues must be sent to [[email protected]](mailto:[email protected]). |
| 73 | + |
| 74 | +### Bug Bounty |
| 75 | + |
| 76 | +This is an Open-Source project where most of the work is done by volunteers. |
| 77 | +We appreciate that developers are trying to find security issues in TypeLang |
| 78 | +Components and report them responsibly, but we are currently unable to |
| 79 | +pay bug bounties. |
| 80 | + |
| 81 | +## Pull Request |
| 82 | + |
| 83 | +Before you start, you should be aware that all the code you are going to |
| 84 | +submit must be released under the [MIT license](https://opensource.org/license/mit). |
| 85 | + |
| 86 | +A pull request (or "merge request"), "PR" for short, is the best way to |
| 87 | +provide a bug fix or to propose enhancements to TypeLang Components. |
| 88 | + |
| 89 | +<procedure title="#1: Setup your Environment"> |
| 90 | + <step>Git;</step> |
| 91 | + <step>PHP 8.1 or above.</step> |
| 92 | +</procedure> |
| 93 | + |
| 94 | +<procedure title="#2: Get the Source Code"> |
| 95 | + <step> |
| 96 | + Create a <a href="https://github.com">GitHub</a> account and sign in; |
| 97 | + </step> |
| 98 | + <step> |
| 99 | + Fork an expected repository (click on <shortcut>Fork</shortcut> button); |
| 100 | + </step> |
| 101 | + <step> |
| 102 | + Uncheck the "Copy the X.Y branch only"; |
| 103 | + </step> |
| 104 | + <step> |
| 105 | + After the "forking action" has completed, clone your fork locally |
| 106 | + (this will create a component directory): |
| 107 | + <code-block lang="Bash"> |
| 108 | + git clone [email protected]:USERNAME/COMPONENT_NAME.git |
| 109 | + </code-block> |
| 110 | + </step> |
| 111 | + <step> |
| 112 | + Add the upstream repository as a remote: |
| 113 | + <code-block lang="Bash"> |
| 114 | + cd COMPONENT_NAME |
| 115 | + git remote add upstream https://github.com/php-type-language/COMPONENT_NAME.git |
| 116 | + </code-block> |
| 117 | + </step> |
| 118 | +</procedure> |
| 119 | + |
| 120 | +<procedure title="#3: Choose the right Branch"> |
| 121 | + Since the project is quite simple, you can use the <code>master</code> branch for now. |
| 122 | +</procedure> |
| 123 | + |
| 124 | +<procedure title="#4: Work on your Pull Request"> |
| 125 | + Work on the code as much as you want and commit as much as you want; |
| 126 | + but keep in mind the following: |
| 127 | + <step> |
| 128 | + Add unit or functional tests to prove that the bug is fixed or |
| 129 | + that the new feature actually works; |
| 130 | + </step> |
| 131 | + <step> |
| 132 | + Try hard to not break backward compatibility (if you must do so, try to |
| 133 | + provide a compatibility layer to support the old way) — PRs that |
| 134 | + break backward compatibility have less chance to be merged; |
| 135 | + </step> |
| 136 | + <step> |
| 137 | + Write good commit messages: Start by a short subject line (the first line), |
| 138 | + followed by a blank line and a more detailed description. |
| 139 | + </step> |
| 140 | +</procedure> |
| 141 | + |
| 142 | +<procedure title="#5: Check that the current Tests Pass"> |
| 143 | + Each Component contains a short Composer command that allows you to do this. |
| 144 | + <step> |
| 145 | + Checking the tests. |
| 146 | + <code-block lang="Bash"> |
| 147 | + composer test |
| 148 | + </code-block> |
| 149 | + </step> |
| 150 | + <step> |
| 151 | + Checking and correcting coding style (we follow <a href="https://www.php-fig.org/per/coding-style/">PER Coding Style 2.0</a>). |
| 152 | + <code-block lang="Bash"> |
| 153 | + composer phpcs:fix |
| 154 | + </code-block> |
| 155 | + </step> |
| 156 | + <step> |
| 157 | + Checking for other type errors in the code. |
| 158 | + <code-block lang="Bash"> |
| 159 | + composer linter |
| 160 | + </code-block> |
| 161 | + </step> |
| 162 | +</procedure> |
| 163 | + |
| 164 | +<procedure title="#6: Submit your Pull Request"> |
| 165 | + Whenever you feel that your PR is ready for submission, |
| 166 | + follow the following steps. |
| 167 | + <step> |
| 168 | + Get all the latest changes to the branch |
| 169 | + <code-block lang="Bash"> |
| 170 | + git fetch upstream |
| 171 | + git pull upstream master --ff |
| 172 | + </code-block> |
| 173 | + </step> |
| 174 | + <step> |
| 175 | + You can now make a pull request on GitHub repository. |
| 176 | + </step> |
| 177 | +</procedure> |
0 commit comments