vendor/zendframework/zend-mail/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-mail/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 ## RUNNING TESTS
  38
  39 > ### Note: testing versions prior to 2.4
  40 >
  41 > This component originates with Zend Framework 2. During the lifetime of ZF2,
  42 > testing infrastructure migrated from PHPUnit 3 to PHPUnit 4. In most cases, no
  43 > changes were necessary. However, due to the migration, tests may not run on
  44 > versions < 2.4. As such, you may need to change the PHPUnit dependency if
  45 > attempting a fix on such a version.
  46
  47 To run tests:
  48
  49 - Clone the repository:
  50
  51   ```console
  52   $ git clone git@github.com:zendframework/zend-mail.git
  53   $ cd
  54   ```
  55
  56 - Install dependencies via composer:
  57
  58   ```console
  59   $ curl -sS https://getcomposer.org/installer | php --
  60   $ ./composer.phar install
  61   ```
  62
  63   If you don't have `curl` installed, you can also download `composer.phar` from https://getcomposer.org/
  64
  65 - Run the tests via `phpunit` and the provided PHPUnit config, like in this example:
  66
  67   ```console
  68   $ ./vendor/bin/phpunit
  69   ```
  70
  71 You can turn on conditional tests with the phpunit.xml file.
  72 To do so:
  73
  74  -  Copy `phpunit.xml.dist` file to `phpunit.xml`
  75  -  Edit `phpunit.xml` to enable any specific functionality you
  76     want to test, as well as to provide test values to utilize.
  77
  78 ## Running Coding Standards Checks
  79
  80 This component uses [phpcs](https://github.com/squizlabs/PHP_CodeSniffer) for coding
  81 standards checks, and provides configuration for our selected checks.
  82 `phpcs` is installed by default via Composer.
  83
  84 To run checks only:
  85
  86 ```console
  87 $ composer cs-check
  88 ```
  89
  90 `phpcs` also includes a tool for fixing most CS violations, `phpcbf`:
  91
  92
  93 ```console
  94 $ composer cs-fix
  95 ```
  96
  97 If you allow `phpcbf` to fix CS issues, please re-run the tests to ensure
  98 they pass, and make sure you add and commit the changes after verification.
  99
 100 ## Recommended Workflow for Contributions
 101
 102 Your first step is to establish a public repository from which we can
 103 pull your work into the master repository. We recommend using
 104 [GitHub](https://github.com), as that is where the component is already hosted.
 105
 106 1. Setup a [GitHub account](http://github.com/), if you haven't yet
 107 2. Fork the repository (http://github.com/zendframework/zend-mail)
 108 3. Clone the canonical repository locally and enter it.
 109
 110    ```console
 111    $ git clone git://github.com:zendframework/zend-mail.git
 112    $ cd zend-mail
 113    ```
 114
 115 4. Add a remote to your fork; substitute your GitHub username in the command
 116    below.
 117
 118    ```console
 119    $ git remote add {username} git@github.com:{username}/zend-mail.git
 120    $ git fetch {username}
 121    ```
 122
 123 ### Keeping Up-to-Date
 124
 125 Periodically, you should update your fork or personal repository to
 126 match the canonical ZF repository. Assuming you have setup your local repository
 127 per the instructions above, you can do the following:
 128
 129
 130 ```console
 131 $ git checkout master
 132 $ git fetch origin
 133 $ git rebase origin/master
 134 # OPTIONALLY, to keep your remote up-to-date -
 135 $ git push {username} master:master
 136 ```
 137
 138 If you're tracking other branches -- for example, the "develop" branch, where
 139 new feature development occurs -- you'll want to do the same operations for that
 140 branch; simply substitute  "develop" for "master".
 141
 142 ### Working on a patch
 143
 144 We recommend you do each new feature or bugfix in a new branch. This simplifies
 145 the task of code review as well as the task of merging your changes into the
 146 canonical repository.
 147
 148 A typical workflow will then consist of the following:
 149
 150 1. Create a new local branch based off either your master or develop branch.
 151 2. Switch to your new local branch. (This step can be combined with the
 152    previous step with the use of `git checkout -b`.)
 153 3. Do some work, commit, repeat as necessary.
 154 4. Push the local branch to your remote repository.
 155 5. Send a pull request.
 156
 157 The mechanics of this process are actually quite trivial. Below, we will
 158 create a branch for fixing an issue in the tracker.
 159
 160 ```console
 161 $ git checkout -b hotfix/9295
 162 Switched to a new branch 'hotfix/9295'
 163 ```
 164
 165 ... do some work ...
 166
 167
 168 ```console
 169 $ git commit
 170 ```
 171
 172 ... write your log message ...
 173
 174
 175 ```console
 176 $ git push {username} hotfix/9295:hotfix/9295
 177 Counting objects: 38, done.
 178 Delta compression using up to 2 threads.
 179 Compression objects: 100% (18/18), done.
 180 Writing objects: 100% (20/20), 8.19KiB, done.
 181 Total 20 (delta 12), reused 0 (delta 0)
 182 To ssh://git@github.com/{username}/zend-mail.git
 183    b5583aa..4f51698  HEAD -> master
 184 ```
 185
 186 To send a pull request, you have two options.
 187
 188 If using GitHub, you can do the pull request from there. Navigate to
 189 your repository, select the branch you just created, and then select the
 190 "Pull Request" button in the upper right. Select the user/organization
 191 "zendframework" as the recipient.
 192
 193 If using your own repository - or even if using GitHub - you can use `git
 194 format-patch` to create a patchset for us to apply; in fact, this is
 195 **recommended** for security-related patches. If you use `format-patch`, please
 196 send the patches as attachments to:
 197
 198 -  zf-devteam@zend.com for patches without security implications
 199 -  zf-security@zend.com for security patches
 200
 201 #### What branch to issue the pull request against?
 202
 203 Which branch should you issue a pull request against?
 204
 205 - For fixes against the stable release, issue the pull request against the
 206   "master" branch.
 207 - For new features, or fixes that introduce new elements to the public API (such
 208   as new public methods or properties), issue the pull request against the
 209   "develop" branch.
 210
 211 ### Branch Cleanup
 212
 213 As you might imagine, if you are a frequent contributor, you'll start to
 214 get a ton of branches both locally and on your remote.
 215
 216 Once you know that your changes have been accepted to the master
 217 repository, we suggest doing some cleanup of these branches.
 218
 219 -  Local branch cleanup
 220
 221    ```console
 222    $ git branch -d <branchname>
 223    ```
 224
 225 -  Remote branch removal
 226
 227    ```console
 228    $ git push {username} :<branchname>
 229    ```
 230
 231
 232 ## Conduct
 233
 234 Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project.