Chris@0: # CONTRIBUTING
Chris@0: 
Chris@0: ## RESOURCES
Chris@0: 
Chris@0: If you wish to contribute to Zend Framework, please be sure to
Chris@0: read/subscribe to the following resources:
Chris@0: 
Chris@0:  -  [Coding Standards](https://github.com/zendframework/zf2/wiki/Coding-Standards)
Chris@0:  -  [Contributor's Guide](http://framework.zend.com/participate/contributor-guide)
Chris@0:  -  ZF Contributor's mailing list:
Chris@0:     Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html
Chris@0:     Subscribe: zf-contributors-subscribe@lists.zend.com
Chris@0:  -  ZF Contributor's IRC channel:
Chris@0:     #zftalk.dev on Freenode.net
Chris@0: 
Chris@0: If you are working on new features or refactoring [create a proposal](https://github.com/zendframework/zend-stdlib/issues/new).
Chris@0: 
Chris@0: ## Reporting Potential Security Issues
Chris@0: 
Chris@0: If you have encountered a potential security vulnerability, please **DO NOT** report it on the public
Chris@0: issue tracker: send it to us at [zf-security@zend.com](mailto:zf-security@zend.com) instead.
Chris@0: We will work with you to verify the vulnerability and patch it as soon as possible.
Chris@0: 
Chris@0: When reporting issues, please provide the following information:
Chris@0: 
Chris@0: - Component(s) affected
Chris@0: - A description indicating how to reproduce the issue
Chris@0: - A summary of the security vulnerability and impact
Chris@0: 
Chris@0: We request that you contact us via the email address above and give the project
Chris@0: contributors a chance to resolve the vulnerability and issue a new release prior
Chris@0: to any public exposure; this helps protect users and provides them with a chance
Chris@0: to upgrade and/or update in order to protect their applications.
Chris@0: 
Chris@0: For sensitive email communications, please use [our PGP key](http://framework.zend.com/zf-security-pgp-key.asc).
Chris@0: 
Chris@0: ## RUNNING TESTS
Chris@0: 
Chris@0: > ### Note: testing versions prior to 2.4
Chris@0: >
Chris@0: > This component originates with Zend Framework 2. During the lifetime of ZF2,
Chris@0: > testing infrastructure migrated from PHPUnit 3 to PHPUnit 4. In most cases, no
Chris@0: > changes were necessary. However, due to the migration, tests may not run on
Chris@0: > versions < 2.4. As such, you may need to change the PHPUnit dependency if
Chris@0: > attempting a fix on such a version.
Chris@0: 
Chris@0: To run tests:
Chris@0: 
Chris@0: - Clone the repository:
Chris@0: 
Chris@0:   ```console
Chris@0:   $ git clone git@github.com:zendframework/zend-stdlib.git
Chris@0:   $ cd
Chris@0:   ```
Chris@0: 
Chris@0: - Install dependencies via composer:
Chris@0: 
Chris@0:   ```console
Chris@0:   $ curl -sS https://getcomposer.org/installer | php --
Chris@0:   $ ./composer.phar install
Chris@0:   ```
Chris@0: 
Chris@0:   If you don't have `curl` installed, you can also download `composer.phar` from https://getcomposer.org/
Chris@0: 
Chris@0: - Run the tests via `phpunit` and the provided PHPUnit config, like in this example:
Chris@0: 
Chris@0:   ```console
Chris@0:   $ ./vendor/bin/phpunit
Chris@0:   ```
Chris@0: 
Chris@0: You can turn on conditional tests with the phpunit.xml file.
Chris@0: To do so:
Chris@0: 
Chris@0:  -  Copy `phpunit.xml.dist` file to `phpunit.xml`
Chris@0:  -  Edit `phpunit.xml` to enable any specific functionality you
Chris@0:     want to test, as well as to provide test values to utilize.
Chris@0: 
Chris@0: ## Running Coding Standards Checks
Chris@0: 
Chris@0: This component uses [php-cs-fixer](http://cs.sensiolabs.org/) for coding
Chris@0: standards checks, and provides configuration for our selected checks.
Chris@0: `php-cs-fixer` is installed by default via Composer.
Chris@0: 
Chris@0: To run checks only:
Chris@0: 
Chris@0: ```console
Chris@0: $ ./vendor/bin/php-cs-fixer fix . -v --diff --dry-run --config-file=.php_cs
Chris@0: ```
Chris@0: 
Chris@0: To have `php-cs-fixer` attempt to fix problems for you, omit the `--dry-run`
Chris@0: flag:
Chris@0: 
Chris@0: ```console
Chris@0: $ ./vendor/bin/php-cs-fixer fix . -v --diff --config-file=.php_cs
Chris@0: ```
Chris@0: 
Chris@0: If you allow php-cs-fixer to fix CS issues, please re-run the tests to ensure
Chris@0: they pass, and make sure you add and commit the changes after verification.
Chris@0: 
Chris@0: ## Benchmarks
Chris@0: 
Chris@0: We provide benchmark tests for zend-stdlib under the directory [benchmark/](benchmark/),
Chris@0: using.  [athletic](https://github.com/polyfractal/athletic).  You can execute
Chris@0: the benchmarks running the following command:
Chris@0: 
Chris@0: ```bash
Chris@0: $ ./vendor/bin/athletic -p benchmark
Chris@0: ```
Chris@0: 
Chris@0: ## Recommended Workflow for Contributions
Chris@0: 
Chris@0: Your first step is to establish a public repository from which we can
Chris@0: pull your work into the master repository. We recommend using
Chris@0: [GitHub](https://github.com), as that is where the component is already hosted.
Chris@0: 
Chris@0: 1. Setup a [GitHub account](http://github.com/), if you haven't yet
Chris@0: 2. Fork the repository (http://github.com/zendframework/zend-stdlib)
Chris@0: 3. Clone the canonical repository locally and enter it.
Chris@0: 
Chris@0:    ```console
Chris@0:    $ git clone git://github.com:zendframework/zend-stdlib.git
Chris@0:    $ cd zend-stdlib
Chris@0:    ```
Chris@0: 
Chris@0: 4. Add a remote to your fork; substitute your GitHub username in the command
Chris@0:    below.
Chris@0: 
Chris@0:    ```console
Chris@0:    $ git remote add {username} git@github.com:{username}/zend-stdlib.git
Chris@0:    $ git fetch {username}
Chris@0:    ```
Chris@0: 
Chris@0: ### Keeping Up-to-Date
Chris@0: 
Chris@0: Periodically, you should update your fork or personal repository to
Chris@0: match the canonical ZF repository. Assuming you have setup your local repository
Chris@0: per the instructions above, you can do the following:
Chris@0: 
Chris@0: 
Chris@0: ```console
Chris@0: $ git checkout master
Chris@0: $ git fetch origin
Chris@0: $ git rebase origin/master
Chris@0: # OPTIONALLY, to keep your remote up-to-date -
Chris@0: $ git push {username} master:master
Chris@0: ```
Chris@0: 
Chris@0: If you're tracking other branches -- for example, the "develop" branch, where
Chris@0: new feature development occurs -- you'll want to do the same operations for that
Chris@0: branch; simply substitute  "develop" for "master".
Chris@0: 
Chris@0: ### Working on a patch
Chris@0: 
Chris@0: We recommend you do each new feature or bugfix in a new branch. This simplifies
Chris@0: the task of code review as well as the task of merging your changes into the
Chris@0: canonical repository.
Chris@0: 
Chris@0: A typical workflow will then consist of the following:
Chris@0: 
Chris@0: 1. Create a new local branch based off either your master or develop branch.
Chris@0: 2. Switch to your new local branch. (This step can be combined with the
Chris@0:    previous step with the use of `git checkout -b`.)
Chris@0: 3. Do some work, commit, repeat as necessary.
Chris@0: 4. Push the local branch to your remote repository.
Chris@0: 5. Send a pull request.
Chris@0: 
Chris@0: The mechanics of this process are actually quite trivial. Below, we will
Chris@0: create a branch for fixing an issue in the tracker.
Chris@0: 
Chris@0: ```console
Chris@0: $ git checkout -b hotfix/9295
Chris@0: Switched to a new branch 'hotfix/9295'
Chris@0: ```
Chris@0: 
Chris@0: ... do some work ...
Chris@0: 
Chris@0: 
Chris@0: ```console
Chris@0: $ git commit
Chris@0: ```
Chris@0: 
Chris@0: ... write your log message ...
Chris@0: 
Chris@0: 
Chris@0: ```console
Chris@0: $ git push {username} hotfix/9295:hotfix/9295
Chris@0: Counting objects: 38, done.
Chris@0: Delta compression using up to 2 threads.
Chris@0: Compression objects: 100% (18/18), done.
Chris@0: Writing objects: 100% (20/20), 8.19KiB, done.
Chris@0: Total 20 (delta 12), reused 0 (delta 0)
Chris@0: To ssh://git@github.com/{username}/zend-stdlib.git
Chris@0:    b5583aa..4f51698  HEAD -> master
Chris@0: ```
Chris@0: 
Chris@0: To send a pull request, you have two options.
Chris@0: 
Chris@0: If using GitHub, you can do the pull request from there. Navigate to
Chris@0: your repository, select the branch you just created, and then select the
Chris@0: "Pull Request" button in the upper right. Select the user/organization
Chris@0: "zendframework" as the recipient.
Chris@0: 
Chris@0: If using your own repository - or even if using GitHub - you can use `git
Chris@0: format-patch` to create a patchset for us to apply; in fact, this is
Chris@0: **recommended** for security-related patches. If you use `format-patch`, please
Chris@0: send the patches as attachments to:
Chris@0: 
Chris@0: -  zf-devteam@zend.com for patches without security implications
Chris@0: -  zf-security@zend.com for security patches
Chris@0: 
Chris@0: #### What branch to issue the pull request against?
Chris@0: 
Chris@0: Which branch should you issue a pull request against?
Chris@0: 
Chris@0: - For fixes against the stable release, issue the pull request against the
Chris@0:   "master" branch.
Chris@0: - For new features, or fixes that introduce new elements to the public API (such
Chris@0:   as new public methods or properties), issue the pull request against the
Chris@0:   "develop" branch.
Chris@0: 
Chris@0: ### Branch Cleanup
Chris@0: 
Chris@0: As you might imagine, if you are a frequent contributor, you'll start to
Chris@0: get a ton of branches both locally and on your remote.
Chris@0: 
Chris@0: Once you know that your changes have been accepted to the master
Chris@0: repository, we suggest doing some cleanup of these branches.
Chris@0: 
Chris@0: -  Local branch cleanup
Chris@0: 
Chris@0:    ```console
Chris@0:    $ git branch -d <branchname>
Chris@0:    ```
Chris@0: 
Chris@0: -  Remote branch removal
Chris@0: 
Chris@0:    ```console
Chris@0:    $ git push {username} :<branchname>
Chris@0:    ```
Chris@0: 
Chris@0: 
Chris@0: ## Conduct
Chris@0: 
Chris@0: Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project.