|
1 | 1 | # CONTRIBUTING |
2 | 2 |
|
3 | | -Apigility and related modules (of which this is one) are open source and licensed |
4 | | -as [BSD-3-Clause](http://opensource.org/licenses/BSD-3-Clause). Contributions |
5 | | -are welcome in the form of issue reports and pull requests. |
6 | | - |
7 | | -All pull requests should include unit tests when applicable, and should follow |
8 | | -our coding standards (more on these below); failure to do so may result in |
9 | | -rejection of the pull request. If you need help writing tests, please ask on the |
10 | | -developer mailing list and/or in IRC. |
11 | | - |
12 | 3 | ## RESOURCES |
13 | 4 |
|
14 | | -If you wish to contribute to Apigility modules, please be sure to |
| 5 | +If you wish to contribute to this project, please be sure to |
15 | 6 | read/subscribe to the following resources: |
16 | 7 |
|
17 | | - - [Coding Standards](https://github.com/zendframework/zf2/wiki/Coding-Standards) |
18 | | - - [ZF Git Guide](https://github.com/zendframework/zf2/blob/master/README-GIT.md) |
19 | | - - [Apigility developer mailing list](http://bit.ly/apigility-dev) |
20 | | - - Apigility developer IRC channel: #apigility-dev on Freenode.net |
| 8 | + - [Coding Standards](https://github.com/zendframework/zend-coding-standard) |
| 9 | + - [Forums](https://discourse.zendframework.com/c/contributors) |
| 10 | + - [Chat](https://zendframework-slack.herokuapp.com) |
| 11 | + - [Code of Conduct](CODE_OF_CONDUCT.md) |
| 12 | + |
| 13 | +If you are working on new features or refactoring |
| 14 | +[create a proposal](https://github.com/zfcampus/zf-api-problem/issues/new). |
21 | 15 |
|
22 | | -If you are working on new features, refactoring an existing module, or proposing |
23 | | -a new module, please send an email to the developer mailing list. |
| 16 | +## RUNNING TESTS |
24 | 17 |
|
25 | | -## REPORTING POTENTIAL SECURITY ISSUES |
| 18 | +To run tests: |
26 | 19 |
|
27 | | -If you have encountered a potential security vulnerability in any Apigility |
28 | | -module, please report it to us at [zf-security@zend.com](mailto:zf-security@zend.com). |
29 | | -We will work with you to verify the vulnerability and patch it. |
| 20 | +- Clone the repository: |
30 | 21 |
|
31 | | -When reporting issues, please provide the following information: |
| 22 | + ```console |
| 23 | + $ git clone git://github.com/zfcampus/zf-api-problem.git |
| 24 | + $ cd zf-api-problem |
| 25 | + ``` |
32 | 26 |
|
33 | | -- Module(s) affected |
34 | | -- A description indicating how to reproduce the issue |
35 | | -- A summary of the security vulnerability and impact |
| 27 | +- Install dependencies via composer: |
36 | 28 |
|
37 | | -We request that you contact us via the email address above and give the project |
38 | | -contributors a chance to resolve the vulnerability and issue a new release prior |
39 | | -to any public exposure; this helps protect Apigility users, and provides them |
40 | | -with a chance to upgrade and/or update in order to protect their applications. |
| 29 | + ```console |
| 30 | + $ composer install |
| 31 | + ``` |
41 | 32 |
|
42 | | -For sensitive email communications, please use |
43 | | -[our PGP key](http://framework.zend.com/zf-security-pgp-key.asc). |
| 33 | + If you don't have `composer` installed, please download it from https://getcomposer.org/download/ |
44 | 34 |
|
45 | | -## RUNNING TESTS |
| 35 | +- Make sure that `zendframework/zend-test` is installed: |
| 36 | + |
| 37 | + ```console |
| 38 | + $ composer require --dev zendframework/zend-test |
| 39 | + ``` |
| 40 | + |
| 41 | +- Run the tests using the "test" command shipped in the `composer.json`: |
| 42 | + |
| 43 | + ```console |
| 44 | + $ composer test |
| 45 | + ``` |
| 46 | + |
| 47 | +You can turn on conditional tests with the `phpunit.xml` file. |
| 48 | +To do so: |
| 49 | + |
| 50 | + - Copy `phpunit.xml.dist` file to `phpunit.xml` |
| 51 | + - Edit `phpunit.xml` to enable any specific functionality you |
| 52 | + want to test, as well as to provide test values to utilize. |
| 53 | + |
| 54 | +## Running Coding Standards Checks |
| 55 | + |
| 56 | +First, ensure you've installed dependencies via composer, per the previous |
| 57 | +section on running tests. |
46 | 58 |
|
47 | | -First, use [Composer](https://getcomposer.org) to install all dependencies: |
| 59 | +Make sure that `squizlabs/php_codesniffer` is installed: |
48 | 60 |
|
49 | | -```bash |
50 | | -$ composer install |
| 61 | +```console |
| 62 | +$ composer require --dev squizlabs/php_codesniffer |
51 | 63 | ``` |
52 | 64 |
|
53 | | -Make sure that `zendframework/zend-test` is installed: |
| 65 | +To run CS checks only: |
54 | 66 |
|
55 | | -```bash |
56 | | -$ composer require --dev zendframework/zend-test |
| 67 | +```console |
| 68 | +$ composer cs-check |
57 | 69 | ``` |
58 | 70 |
|
59 | | -To run tests: |
| 71 | +To attempt to automatically fix common CS issues: |
60 | 72 |
|
61 | | -```bash |
62 | | -$ composer test |
| 73 | +```console |
| 74 | +$ composer cs-fix |
63 | 75 | ``` |
64 | 76 |
|
65 | | -## CODING STANDARDS |
| 77 | +If the above fixes any CS issues, please re-run the tests to ensure |
| 78 | +they pass, and make sure you add and commit the changes after verification. |
66 | 79 |
|
67 | | -While Apigility uses Zend Framework coding standards, in practice, we verify |
68 | | -against [PSR-2](http://www.php-fig.org/psr/psr-2/). |
| 80 | +## Recommended Workflow for Contributions |
69 | 81 |
|
70 | | -First, ensure you've installed dependencies via composer: |
| 82 | +Your first step is to establish a public repository from which we can |
| 83 | +pull your work into the master repository. We recommend using |
| 84 | +[GitHub](https://github.com), as that is where the component is already hosted. |
71 | 85 |
|
72 | | -```bash |
73 | | -$ composer require --dev squizlabs/php_codesniffer |
| 86 | +1. Setup a [GitHub account](https://github.com/), if you haven't yet |
| 87 | +2. Fork the repository (https://github.com/zfcampus/zf-api-problem) |
| 88 | +3. Clone the canonical repository locally and enter it. |
| 89 | + |
| 90 | + ```console |
| 91 | + $ git clone git://github.com/zfcampus/zf-api-problem.git |
| 92 | + $ cd zf-api-problem |
| 93 | + ``` |
| 94 | + |
| 95 | +4. Add a remote to your fork; substitute your GitHub username in the command |
| 96 | + below. |
| 97 | + |
| 98 | + ```console |
| 99 | + $ git remote add {username} git@github.com:{username}/zf-api-problem.git |
| 100 | + $ git fetch {username} |
| 101 | + ``` |
| 102 | + |
| 103 | +### Keeping Up-to-Date |
| 104 | + |
| 105 | +Periodically, you should update your fork or personal repository to |
| 106 | +match the canonical ZF repository. Assuming you have setup your local repository |
| 107 | +per the instructions above, you can do the following: |
| 108 | + |
| 109 | + |
| 110 | +```console |
| 111 | +$ git checkout master |
| 112 | +$ git fetch origin |
| 113 | +$ git rebase origin/master |
| 114 | +# OPTIONALLY, to keep your remote up-to-date - |
| 115 | +$ git push {username} master:master |
74 | 116 | ``` |
75 | 117 |
|
76 | | -To check for CS issues: |
| 118 | +If you're tracking other branches -- for example, the "develop" branch, where |
| 119 | +new feature development occurs -- you'll want to do the same operations for that |
| 120 | +branch; simply substitute "develop" for "master". |
77 | 121 |
|
78 | | -```bash |
79 | | -$ composer cs-check |
| 122 | +### Working on a patch |
| 123 | + |
| 124 | +We recommend you do each new feature or bugfix in a new branch. This simplifies |
| 125 | +the task of code review as well as the task of merging your changes into the |
| 126 | +canonical repository. |
| 127 | + |
| 128 | +A typical workflow will then consist of the following: |
| 129 | + |
| 130 | +1. Create a new local branch based off either your master or develop branch. |
| 131 | +2. Switch to your new local branch. (This step can be combined with the |
| 132 | + previous step with the use of `git checkout -b`.) |
| 133 | +3. Do some work, commit, repeat as necessary. |
| 134 | +4. Push the local branch to your remote repository. |
| 135 | +5. Send a pull request. |
| 136 | + |
| 137 | +The mechanics of this process are actually quite trivial. Below, we will |
| 138 | +create a branch for fixing an issue in the tracker. |
| 139 | + |
| 140 | +```console |
| 141 | +$ git checkout -b hotfix/9295 |
| 142 | +Switched to a new branch 'hotfix/9295' |
80 | 143 | ``` |
81 | 144 |
|
82 | | -This will report CS issues. Alternately, you can have most errors automatically |
83 | | -fixed as well: |
| 145 | +... do some work ... |
84 | 146 |
|
85 | | -```bash |
86 | | -$ composer cs-fix |
| 147 | + |
| 148 | +```console |
| 149 | +$ git commit |
| 150 | +``` |
| 151 | + |
| 152 | +... write your log message ... |
| 153 | + |
| 154 | + |
| 155 | +```console |
| 156 | +$ git push {username} hotfix/9295:hotfix/9295 |
| 157 | +Counting objects: 38, done. |
| 158 | +Delta compression using up to 2 threads. |
| 159 | +Compression objects: 100% (18/18), done. |
| 160 | +Writing objects: 100% (20/20), 8.19KiB, done. |
| 161 | +Total 20 (delta 12), reused 0 (delta 0) |
| 162 | +To ssh://git@github.com/{username}/zf-api-problem.git |
| 163 | + b5583aa..4f51698 HEAD -> master |
87 | 164 | ``` |
88 | 165 |
|
89 | | -After running `composer cs-fix`, be sure to add and commit any files that were |
90 | | -updated, after first verifying that the changes do not break tests. |
| 166 | +To send a pull request, you have two options. |
| 167 | + |
| 168 | +If using GitHub, you can do the pull request from there. Navigate to |
| 169 | +your repository, select the branch you just created, and then select the |
| 170 | +"Pull Request" button in the upper right. Select the user/organization |
| 171 | +"zfcampus" (or whatever the upstream organization is) as the recipient. |
| 172 | + |
| 173 | +#### What branch to issue the pull request against? |
| 174 | + |
| 175 | +Which branch should you issue a pull request against? |
| 176 | + |
| 177 | +- For fixes against the stable release, issue the pull request against the |
| 178 | + "master" branch. |
| 179 | +- For new features, or fixes that introduce new elements to the public API (such |
| 180 | + as new public methods or properties), issue the pull request against the |
| 181 | + "develop" branch. |
| 182 | + |
| 183 | +### Branch Cleanup |
| 184 | + |
| 185 | +As you might imagine, if you are a frequent contributor, you'll start to |
| 186 | +get a ton of branches both locally and on your remote. |
| 187 | + |
| 188 | +Once you know that your changes have been accepted to the master |
| 189 | +repository, we suggest doing some cleanup of these branches. |
| 190 | + |
| 191 | +- Local branch cleanup |
| 192 | + |
| 193 | + ```console |
| 194 | + $ git branch -d <branchname> |
| 195 | + ``` |
91 | 196 |
|
92 | | -## Conduct |
| 197 | +- Remote branch removal |
93 | 198 |
|
94 | | -Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project. |
| 199 | + ```console |
| 200 | + $ git push {username} :<branchname> |
| 201 | + ``` |
0 commit comments