5 If you wish to contribute to Zend Framework, please be sure to
6 read/subscribe to the following resources:
8 - [Coding Standards](https://github.com/zendframework/zf2/wiki/Coding-Standards)
9 - [Contributor's Guide](http://framework.zend.com/participate/contributor-guide)
10 - ZF Contributor's mailing list:
11 Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html
12 Subscribe: zf-contributors-subscribe@lists.zend.com
13 - ZF Contributor's IRC channel:
14 #zftalk.dev on Freenode.net
16 If you are working on new features or refactoring [create a proposal](https://github.com/zendframework/zend-diactoros/issues/new).
18 ## Reporting Potential Security Issues
20 If you have encountered a potential security vulnerability, please **DO NOT** report it on the public
21 issue tracker: send it to us at [zf-security@zend.com](mailto:zf-security@zend.com) instead.
22 We will work with you to verify the vulnerability and patch it as soon as possible.
24 When reporting issues, please provide the following information:
26 - Component(s) affected
27 - A description indicating how to reproduce the issue
28 - A summary of the security vulnerability and impact
30 We request that you contact us via the email address above and give the project
31 contributors a chance to resolve the vulnerability and issue a new release prior
32 to any public exposure; this helps protect users and provides them with a chance
33 to upgrade and/or update in order to protect their applications.
35 For sensitive email communications, please use [our PGP key](http://framework.zend.com/zf-security-pgp-key.asc).
39 Documentation is in [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/),
40 and rendered using [bookdown](http://bookdown.io). Please read and follow the [general documentation
41 guidelines](https://github.com/zendframework/documentation/blob/master/CONTRIBUTING.md) when
42 providing documentation.
44 All new features **must** include documentation before they may be accepted and merged.
50 - Clone the repository:
53 $ git clone git@github.com:zendframework/zend-diactoros.git
57 - Install dependencies via composer:
60 $ curl -sS https://getcomposer.org/installer | php --
61 $ ./composer.phar install
64 If you don't have `curl` installed, you can also download `composer.phar` from https://getcomposer.org/
66 - Run the tests via `phpunit` and the provided PHPUnit config, like in this example:
69 $ ./vendor/bin/phpunit
72 ## Running Coding Standards Checks
74 This component uses [phpcs](https://github.com/squizlabs/PHP_CodeSniffer) for coding
75 standards checks, and provides configuration for our selected checks.
76 `phpcs` is installed by default via Composer.
84 `phpcs` also installs a tool named `phpcbf` which can attempt to fix problems
91 If you allow phpcbf to fix CS issues, please re-run the tests to ensure
92 they pass, and make sure you add and commit the changes after verification.
94 ## Recommended Workflow for Contributions
96 Your first step is to establish a public repository from which we can
97 pull your work into the master repository. We recommend using
98 [GitHub](https://github.com), as that is where the component is already hosted.
100 1. Setup a [GitHub account](http://github.com/), if you haven't yet
101 2. Fork the repository (http://github.com/zendframework/zend-diactoros)
102 3. Clone the canonical repository locally and enter it.
105 $ git clone git://github.com/zendframework/zend-diactoros.git
109 4. Add a remote to your fork; substitute your GitHub username in the command
113 $ git remote add {username} git@github.com:{username}/zend-diactoros.git
114 $ git fetch {username}
117 ### Keeping Up-to-Date
119 Periodically, you should update your fork or personal repository to
120 match the canonical repository. Assuming you have setup your local repository
121 per the instructions above, you can do the following:
125 $ git checkout master
127 $ git rebase origin/master
128 # OPTIONALLY, to keep your remote up-to-date -
129 $ git push {username} master:master
132 If you're tracking other branches -- for example, the "develop" branch, where
133 new feature development occurs -- you'll want to do the same operations for that
134 branch; simply substitute "develop" for "master".
136 ### Working on a patch
138 We recommend you do each new feature or bugfix in a new branch. This simplifies
139 the task of code review as well as the task of merging your changes into the
140 canonical repository.
142 A typical workflow will then consist of the following:
144 1. Create a new local branch based off either your master or develop branch.
145 2. Switch to your new local branch. (This step can be combined with the
146 previous step with the use of `git checkout -b`.)
147 3. Do some work, commit, repeat as necessary.
148 4. Push the local branch to your remote repository.
149 5. Send a pull request.
151 The mechanics of this process are actually quite trivial. Below, we will
152 create a branch for fixing an issue in the tracker.
155 $ git checkout -b hotfix/9295
156 Switched to a new branch 'hotfix/9295'
166 ... write your log message ...
170 $ git push {username} hotfix/9295:hotfix/9295
171 Counting objects: 38, done.
172 Delta compression using up to 2 threads.
173 Compression objects: 100% (18/18), done.
174 Writing objects: 100% (20/20), 8.19KiB, done.
175 Total 20 (delta 12), reused 0 (delta 0)
176 To ssh://git@github.com/{username}/zend-diactoros.git
177 b5583aa..4f51698 HEAD -> master
180 To send a pull request, you have two options.
182 If using GitHub, you can do the pull request from there. Navigate to
183 your repository, select the branch you just created, and then select the
184 "Pull Request" button in the upper right. Select the user/organization
185 "zendframework" as the recipient.
187 If using your own repository - or even if using GitHub - you can use `git
188 format-patch` to create a patchset for us to apply; in fact, this is
189 **recommended** for security-related patches. If you use `format-patch`, please
190 send the patches as attachments to:
192 - zf-devteam@zend.com for patches without security implications
193 - zf-security@zend.com for security patches
195 #### What branch to issue the pull request against?
197 Which branch should you issue a pull request against?
199 - For fixes against the stable release, issue the pull request against the
201 - For new features, or fixes that introduce new elements to the public API (such
202 as new public methods or properties), issue the pull request against the
207 As you might imagine, if you are a frequent contributor, you'll start to
208 get a ton of branches both locally and on your remote.
210 Once you know that your changes have been accepted to the master
211 repository, we suggest doing some cleanup of these branches.
213 - Local branch cleanup
216 $ git branch -d <branchname>
219 - Remote branch removal
222 $ git push {username} :<branchname>
228 Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project.