|
| 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 | + |
| 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-xml2json/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 [[email protected]](mailto:[email protected]) 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 [email protected]:zendframework/zend-xml2json.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 [php-cs-fixer](http://cs.sensiolabs.org/) for coding |
| 81 | +standards checks, and provides configuration for our selected checks. |
| 82 | +`php-cs-fixer` is installed by default via Composer. |
| 83 | + |
| 84 | +To run checks only: |
| 85 | + |
| 86 | +```console |
| 87 | +$ ./vendor/bin/php-cs-fixer fix . -v --diff --dry-run --config-file=.php_cs |
| 88 | +``` |
| 89 | + |
| 90 | +To have `php-cs-fixer` attempt to fix problems for you, omit the `--dry-run` |
| 91 | +flag: |
| 92 | + |
| 93 | +```console |
| 94 | +$ ./vendor/bin/php-cs-fixer fix . -v --diff --config-file=.php_cs |
| 95 | +``` |
| 96 | + |
| 97 | +If you allow php-cs-fixer 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-xml2json) |
| 108 | +3. Clone the canonical repository locally and enter it. |
| 109 | + |
| 110 | + ```console |
| 111 | + $ git clone git://github.com:zendframework/zend-xml2json.git |
| 112 | + $ cd zend-xml2json |
| 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} [email protected]:{username}/zend-xml2json.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://[email protected]/{username}/zend-xml2json.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 | +- [email protected] for patches without security implications |
| 199 | +- [email protected] 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. |
0 commit comments