www.aleph1.co.uk Git - yaffs-website/blob - vendor/zendframework/zend-diactoros/CONTRIBUTING.md

   1 # CONTRIBUTING
   2
   3 ## RESOURCES
   4
   5 If you wish to contribute to Zend Framework, please be sure to
   6 read/subscribe to the following resources:
   7
   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
  15
  16 If you are working on new features or refactoring [create a proposal](https://github.com/zendframework/zend-diactoros/issues/new).
  17
  18 ## Reporting Potential Security Issues
  19
  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.
  23
  24 When reporting issues, please provide the following information:
  25
  26 - Component(s) affected
  27 - A description indicating how to reproduce the issue
  28 - A summary of the security vulnerability and impact
  29
  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.
  34
  35 For sensitive email communications, please use [our PGP key](http://framework.zend.com/zf-security-pgp-key.asc).
  36
  37 ## Documentation
  38
  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.
  43
  44 All new features **must** include documentation before they may be accepted and merged.
  45
  46 ## RUNNING TESTS
  47
  48 To run tests:
  49
  50 - Clone the repository:
  51
  52   ```console
  53   $ git clone git@github.com:zendframework/zend-diactoros.git
  54   $ cd
  55   ```
  56
  57 - Install dependencies via composer:
  58
  59   ```console
  60   $ curl -sS https://getcomposer.org/installer | php --
  61   $ ./composer.phar install
  62   ```
  63
  64   If you don't have `curl` installed, you can also download `composer.phar` from https://getcomposer.org/
  65
  66 - Run the tests via `phpunit` and the provided PHPUnit config, like in this example:
  67
  68   ```console
  69   $ ./vendor/bin/phpunit
  70   ```
  71
  72 ## Running Coding Standards Checks
  73
  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.
  77
  78 To run checks only:
  79
  80 ```console
  81 $ composer cs-check
  82 ```
  83
  84 `phpcs` also installs a tool named `phpcbf` which can attempt to fix problems
  85 for you:
  86
  87 ```console
  88 $ composer cs-fix
  89 ```
  90
  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.
  93
  94 ## Recommended Workflow for Contributions
  95
  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.
  99
 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.
 103
 104    ```console
 105    $ git clone git://github.com/zendframework/zend-diactoros.git
 106    $ cd zend-diactoros
 107    ```
 108
 109 4. Add a remote to your fork; substitute your GitHub username in the command
 110    below.
 111
 112    ```console
 113    $ git remote add {username} git@github.com:{username}/zend-diactoros.git
 114    $ git fetch {username}
 115    ```
 116
 117 ### Keeping Up-to-Date
 118
 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:
 122
 123
 124 ```console
 125 $ git checkout master
 126 $ git fetch origin
 127 $ git rebase origin/master
 128 # OPTIONALLY, to keep your remote up-to-date -
 129 $ git push {username} master:master
 130 ```
 131
 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".
 135
 136 ### Working on a patch
 137
 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.
 141
 142 A typical workflow will then consist of the following:
 143
 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.
 150
 151 The mechanics of this process are actually quite trivial. Below, we will
 152 create a branch for fixing an issue in the tracker.
 153
 154 ```console
 155 $ git checkout -b hotfix/9295
 156 Switched to a new branch 'hotfix/9295'
 157 ```
 158
 159 ... do some work ...
 160
 161
 162 ```console
 163 $ git commit
 164 ```
 165
 166 ... write your log message ...
 167
 168
 169 ```console
 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
 178 ```
 179
 180 To send a pull request, you have two options.
 181
 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.
 186
 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:
 191
 192 -  zf-devteam@zend.com for patches without security implications
 193 -  zf-security@zend.com for security patches
 194
 195 #### What branch to issue the pull request against?
 196
 197 Which branch should you issue a pull request against?
 198
 199 - For fixes against the stable release, issue the pull request against the
 200   "master" branch.
 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
 203   "develop" branch.
 204
 205 ### Branch Cleanup
 206
 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.
 209
 210 Once you know that your changes have been accepted to the master
 211 repository, we suggest doing some cleanup of these branches.
 212
 213 -  Local branch cleanup
 214
 215    ```console
 216    $ git branch -d <branchname>
 217    ```
 218
 219 -  Remote branch removal
 220
 221    ```console
 222    $ git push {username} :<branchname>
 223    ```
 224
 225
 226 ## Conduct
 227
 228 Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project.