|
| 1 | + |
| 2 | +Testing |
| 3 | +=========== |
| 4 | + |
| 5 | +Continuous integration tests are available at |
| 6 | +https://travis-ci.org/pytest-dev/unittest2pytest/. |
| 7 | + |
| 8 | +Prior to pushing a pull-request to github, please test locally:: |
| 9 | + |
| 10 | + pip install tox pytest |
| 11 | + tox # or tox -e py27,py33,py34 |
| 12 | + |
| 13 | + |
| 14 | +Version Scheme |
| 15 | +================= |
| 16 | + |
| 17 | +Regarding the version scheme, unittest2pytest conforms to :PEP:`440`. |
| 18 | +This basically means that releases will look like `0.3`, `0.3.1`, |
| 19 | +`0.4`, and pre-releases will have versions like `0.3.dev1`, |
| 20 | +`0.3.1.dev0`. |
| 21 | + |
| 22 | + |
| 23 | +How to Release |
| 24 | +================= |
| 25 | + |
| 26 | + |
| 27 | +Preparation |
| 28 | +----------------- |
| 29 | + |
| 30 | +1. Get yourself an account at PyPI_ and TestPyPI_. Fill both |
| 31 | + credentials in your `~/.pypirc` file, as `described in the Python |
| 32 | + Wiki <https://wiki.python.org/moin/TestPyPI>`_. |
| 33 | + |
| 34 | + * In difference to that description, list `pypitest` *first*. This |
| 35 | + will make `zest.releaser` push the release there first giving you |
| 36 | + a chance for last minute fixes. |
| 37 | + |
| 38 | +2. Install `docutils` and `zest.releaser`, a helper for automating |
| 39 | + releasing a Python project:: |
| 40 | + |
| 41 | + pip install --user docutils zest.releaser |
| 42 | + |
| 43 | + |
| 44 | +Full Release Process |
| 45 | +--------------------- |
| 46 | + |
| 47 | +1. Prepare (see above). |
| 48 | + |
| 49 | +2. Implement and close all issues and pull requests in a specific |
| 50 | + milestone. |
| 51 | + |
| 52 | +3. Ensure everything relevant is committed and tested. ``git stash`` |
| 53 | + your local changes which should not go into the release. |
| 54 | + |
| 55 | +4. Be sure that the current code passes tests locally:: |
| 56 | + |
| 57 | + tox -e py27,py33,py34 |
| 58 | + |
| 59 | +5. Be sure `CI tests |
| 60 | + <https://travis-ci.org/pytest-dev/unittest2pytest/>`_ pass. |
| 61 | + |
| 62 | + |
| 63 | +Now we start with the main release process. |
| 64 | + |
| 65 | +6. Set shell variables to be able to copy-and-paste the remaining |
| 66 | + snippets, e.g.:: |
| 67 | + |
| 68 | + version=0.3 |
| 69 | + prev_version=0.2 |
| 70 | + |
| 71 | +7. Create the **release branch**:: |
| 72 | + |
| 73 | + git checkout -b release/$version |
| 74 | + |
| 75 | +8. **Update versions** in source-code, Changelog, etc.:: |
| 76 | + |
| 77 | + prerelease # zest.releaser command |
| 78 | + |
| 79 | + This will |
| 80 | + |
| 81 | + - ask you a few questions - required version, etc. |
| 82 | + - remove `.devN` from the version string |
| 83 | + - update date and version in `CHANGES.rst` |
| 84 | + |
| 85 | +9. Update **``CHANGES.rst``** and **``AUTHORS``**. |
| 86 | + |
| 87 | + Where to look for possible changes? You can look in pull requests, |
| 88 | + issues, commits, mailing list or even the tool's cli options |
| 89 | + (new/removed options). |
| 90 | + |
| 91 | + Authors should be updated based on merged pull requests:: |
| 92 | + |
| 93 | + git shortlog --numbered --summary --email v${prev_version}..HEAD |
| 94 | + |
| 95 | + a. Check if the files are valid reStructuredText by running:: |
| 96 | + |
| 97 | + rst2html CHANGES.rst > /tmp/CHANGES.html |
| 98 | + xdg-open /tmp/CHANGES.html # opens file in your web-browser |
| 99 | + |
| 100 | + b. If everything is fine, commit:: |
| 101 | + |
| 102 | + git commit -m "Update CHANGES and AUTHORS for release $version" \ |
| 103 | + CHANGES.rst AUTHORS.txt |
| 104 | + |
| 105 | + |
| 106 | +10. In the **README**, update the versions in the badge-images and |
| 107 | + related links. |
| 108 | + |
| 109 | + a. Verify the result be running:: |
| 110 | + |
| 111 | + git diff --color-words='.' README.rst |
| 112 | + |
| 113 | + b. Again, check if the files are valid reStructuredText by running:: |
| 114 | + |
| 115 | + rst2html README.rst > /tmp/README.html |
| 116 | + xdg-open /tmp/README.html # opens file in your web-browser |
| 117 | + |
| 118 | + c. If everything is fine, commit:: |
| 119 | + |
| 120 | + git commit -m 'Update versions in README.' README.rst |
| 121 | + README_CHANGE=$(git rev-parse --short HEAD) # remember this commit |
| 122 | + |
| 123 | +11. Adjust whatever else is required for the release *now*. |
| 124 | + |
| 125 | + |
| 126 | +12. Complete the release: |
| 127 | + |
| 128 | + a. Merge into branch `master`:: |
| 129 | + |
| 130 | + git checkout master |
| 131 | + git merge --no-ff -X theirs -m "Finished release $version." \ |
| 132 | + release/$version |
| 133 | + |
| 134 | + b. In case of a merge-conflict, resolve it using:: |
| 135 | + |
| 136 | + git gui # In the context-menu select "Use Local Version" |
| 137 | + git commit -m "Release $version." |
| 138 | + |
| 139 | + |
| 140 | +13. Run the release script ``release`` and it will do: |
| 141 | + |
| 142 | + - create a signed tag for the released version |
| 143 | + - create and sign source archives |
| 144 | + - uploads them to PyPI |
| 145 | + |
| 146 | + :: |
| 147 | + |
| 148 | + release # zest.releaser command |
| 149 | + |
| 150 | + Submit to `testpypi` first! You can not change any file after |
| 151 | + you've uploaded it to PyPI! |
| 152 | + |
| 153 | +14. Push the changes:: |
| 154 | + |
| 155 | + git push --follow-tags origin master |
| 156 | + |
| 157 | +15. Create release on github: |
| 158 | + |
| 159 | + a. Go to the `unittest2pytest release page |
| 160 | + <https://github.com/pytest-dev/unittest2pytest/releases>`_ |
| 161 | + |
| 162 | + b. Edit the latest `tag` details. |
| 163 | + |
| 164 | + c. Copy there changelog for the current release. This should look |
| 165 | + like `this one |
| 166 | + <https://github.com/pytest-dev/unittest2pytest/releases/tag/v0.3>`_ |
| 167 | + |
| 168 | + d. Upload the `.tar.gz`- and `.zip`-archives and GPG-signatures |
| 169 | + that where uploaded to |unittest2pytest@PyPI|_ |
| 170 | + |
| 171 | + Note: If you are using stuff like RequestBlocker or NoScript in |
| 172 | + your web-browser, mind to allow some additional access. |
| 173 | + |
| 174 | + |
| 175 | +Now we are going to perform some **post-release** steps: |
| 176 | + |
| 177 | +16. Forward the release-branch to master and check it out:: |
| 178 | + |
| 179 | + git checkout master |
| 180 | + git branch -f release/$version master |
| 181 | + git checkout release/$version |
| 182 | + |
| 183 | +17. Revert the version-related to the README (using the commit we |
| 184 | + remembered earlier):: |
| 185 | + |
| 186 | + git revert $README_CHANGE |
| 187 | + |
| 188 | +18. Run the release script ``postrelease``:: |
| 189 | + |
| 190 | + postrelease # zest.releaser command |
| 191 | + |
| 192 | + This will |
| 193 | + |
| 194 | + - increment version string for a new release: `3.0 -> 3.1.dev0` |
| 195 | + - prepare `CHANGES.rst` for the next release. |
| 196 | + |
| 197 | + You need to manually check the `README` and the version in |
| 198 | + `CHANGES`. |
| 199 | + |
| 200 | +19. Merge into branch `develop`:: |
| 201 | + |
| 202 | + git checkout develop |
| 203 | + git merge --no-ff -m "Finished release $version." release/$version |
| 204 | + |
| 205 | +20. Check the diffs: it should only be version related stuff:: |
| 206 | + |
| 207 | + git diff origin/develop |
| 208 | + |
| 209 | +21. Push the changes and delete the local release branch:: |
| 210 | + |
| 211 | + git push --follow-tags origin develop master |
| 212 | + git branch -d release/$version |
| 213 | + |
| 214 | + |
| 215 | +.. _PyPI: https://pypi.python.org/ |
| 216 | +.. _TestPyPI: https://testpypi.python.org/pypi |
| 217 | +.. |unittest2pytest@PyPI| replace:: unittest2pytest at PyPI |
| 218 | +.. _unittest2pytest@PyPI: https://pypi.python.org/unittest2pytest |
| 219 | + |
| 220 | +.. |
| 221 | + Local Variables: |
| 222 | + mode: rst |
| 223 | + ispell-local-dictionary: "american" |
| 224 | + coding: utf-8 |
| 225 | + End: |
0 commit comments