Files
@ ea69b2719d8e
Branch filter:
Location: majic-ansible-roles/docs/releaseprocedures.rst
ea69b2719d8e
11.4 KiB
text/prs.fallenstein.rst
MAR-22: Implemented tests for the common role:
- Added missing documentation for pipreqcheck_uid and pipreqcheck_gid
parameters.
- Use static-hashed passwords for reproducibility during testing in test
playbook.
- Install Emacs and libmariadb-client-lgpl-dev-compat via test playbook on one
of the testing instances in order to test related tasks.
- Fixed parameter for connection limitting in test playbook.
- Added explicit parameters to test playbook for pipreqcheck_gid and
pipreqcheck_uid.
- Fixed deployment of ferm configuration file ot include setting user/group and
mode.
- Added tests covering common deployment, deployment when only mandatory
parameters are provided, and deployment when optional parameters are set as
well.
- Added missing documentation for pipreqcheck_uid and pipreqcheck_gid
parameters.
- Use static-hashed passwords for reproducibility during testing in test
playbook.
- Install Emacs and libmariadb-client-lgpl-dev-compat via test playbook on one
of the testing instances in order to test related tasks.
- Fixed parameter for connection limitting in test playbook.
- Added explicit parameters to test playbook for pipreqcheck_gid and
pipreqcheck_uid.
- Fixed deployment of ferm configuration file ot include setting user/group and
mode.
- Added tests covering common deployment, deployment when only mandatory
parameters are provided, and deployment when optional parameters are set as
well.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 | Release procedures
==================
This section documents various release procedures. This includes:
- General versioning schema principles.
- General backporting principles.
- Releases of major versions.
- Releases of minor versions.
- Releases of patch versions.
Versioning schema
-----------------
*Majic Ansible Roles* project employs `semantic versioning
<http://semver.org/>`_ schema. In short:
- Each version is composed of major, minor, and patch number. For example, in
version ``1.2.3``, ``1`` is the major, ``2`` is the minor, and ``3`` is the
patch number.
- Major number is bumped when making a backwards incompatible
change. I.e. anything that depends on *Majic Ansible Roles* may need to make
changes in order to keep working correctly.
- Minor number is bumped when new features or changes are made without breaking
backwards compatibility. I.e. if you were using version ``1.2.3``, you should
be safe to upgrade to version ``1.3.0`` without making any changes to whatever
is using *Majic Ansible Roles*.
- Patch number is bumped when making purely bug-fix backwards compatible
changes. Patch releases are generally more likely to remain stable simply due
to limited scope of changes (new features can sometimes introduce unexpected
bugs). It shouild be noted that due to relatively limited resources I have
(plus, the roles are mainly used by myself :), patch releases might be a bit
more scarce, and I might opt for going for minor release instead to reduce
amount of work needed (backporting and releasing).
In addition to versioning schema, *Majic Ansible Roles* employs a specific
nomenclature for naming the branches:
- All new development and bug-fixing uses master branch as the base.
- Features and bug-fixes are implemented in a local branch based on the master
branch. Local branches are named after the lower-cased issue number. For
example, if the issuer number is ``MAR-43``, the implementation branch will be
named ``mar-43``. Normally these branches are only local, but if necessary
they can be pushed to the repository (for sharing etc).
- Patch releases are based off the maintenance branches. Mainteance branches are
named after the ``MAJOR`` and ``MINOR`` number of the version. For example, if
a new release is made with version ``1.2.0``, the corresponding branch that is
created for maintenance will be named ``1.2`` (notice the absence of ``.0`` at
the end).
Backporting fixes
-----------------
From time to time it might become useful to apply a bug-fix to both the master
branch, and to maintenace branch.
When a bug is discovered in one of the roles (or maybe documentation), and it
should be applied to maintenance branch as well, procedure is as follows:
1. Create a new bug report in `issue tracker
<https://projects.majic.rs/majic-ansible-roles>`_. Target version should be
either the next minor or next major release (i.e. whatver will get released
from the master branch).
2. Create a copy of the bug report, modifying the issue title to include phrase
``(backport to MAJOR.MINOR)`` at the end, with ``MAJOR`` and ``MINOR``
replaced with correct versioning information for the maintenance
branch. Make sure to set correct target version (patch release).
3. Resolve the bug for next major/minor release.
4. Reslove the bug in maintenace branch by backporting (cherry-picking if
possible) the fix into maintenace branch. Make sure to resign (cherry-picking
invalidates signature) and reword (to reference the backport issue) the
commit.
Releasing new minor/major version
---------------------------------
New minor/major releases are based off of the current master branch ``HEAD``.
When releasing a new minor/major version, procedure is as follows:
1. Verify that there are no outstanding issues blocking the release.
2. Switch to the project Python virtual environment::
workon majic-ansible-roles
3. Make sure you are on the ``master`` branch::
git checkout master
4. Extract current version, set release version, and set issue associated with
making the release::
CURRENT_VERSION=$(grep '^version = ' docs/conf.py | sed -e "s/^version = '//;s/'$//")
NEW_VERSION="MAJOR.MINOR.PATCH"
ISSUE="MAR-NUMBER"
5. Double-check what the associated issues is, what the current version string
is, and what the release version will be::
echo "[$ISSUE] $CURRENT_VERSION -> $NEW_VERSION"
6. Create issue branch::
git checkout -b "${ISSUE,,}"
7. Verify that documentation builds and looks correct::
(cd docs/; make clean html; firefox _build/html/index.html)
8. Test all roles using `Molecule <https://molecule.readthedocs.io/>`_ to make
sure no regressions were introduced.
9. Test deployment of test site from scratch to make sure all roles behave
correctly.
10. Add release notes to file ``docs/releasenotes.rst``. Release notes template
should be as follows::
VERSION
-------
GENERAL DESCRIPTION
New roles:
* ``ROLE``, DESCRIPTION.
Breaking changes:
* ``ROLE`` role
* CHANGE DESCRIPTION
New features/improvements:
* ``ROLE`` role
* FEATURE/IMPROVEMENT DESCRIPTION
Bug-fixes:
* ``ROLE`` role
* BUG-FIX DESCRIPTION
11. Clean-up the documentation build, and check what files need to be updated::
(cd docs; make clean; grep -r "${CURRENT_VERSION/./\\.}" .)
12. Update all relevant documents with new version information, as obtained from
the previous command. At the very least this includes changes to:
- ``docs/conf.py``
- ``usage.rst``
13. Ensure documentation builds correctly::
(cd docs/; make clean html)
14. Show the changes before making a commit::
git diff docs/
15. Commit the changes::
git add docs/
git commits -m "$ISSUE: Preparing for release $NEW_VERSION."
16. Create annotated and signed Git tag::
git tag --sign -a "$NEW_VERSION" -m "RELEASE DESCRIPTION"
17. Clean-up the documentation build, check what files need to be switched back
to development version, and determine development version::
(cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)
echo "${NEW_VERSION%.*}-dev"
18. Update all relevant documents with development version information, as
obtained from the previous command. At the very least this includes changes
to:
- ``docs/conf.py``
- ``usage.rst``
19. Show the changes before committing them::
git diff docs/
20. Commit the changes::
git add docs/
git commits -m "$ISSUE: Bumping version to ${NEW_VERSION%.*}-dev (switching back to development)."
21. Verify GnuPG signatures::
git gpgcheck
git verify-tag "$NEW_VERSION"
22. Merge changes back into the master branch::
git checkout master
git merge "${ISSUE,,}"
23. Push the tag and changes to master::
git push
git push origin "${NEW_VERSION}"
24. Create the maintenace branch::
git checkout -b "${NEW_VERSION%.*}" "$NEW_VERSION"
25. Clean-up the documentation build, check what files need to be switched to
maintenace version, and determine maintenace version::
(cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)
echo "${NEW_VERSION%.*}-maint"
26. Update all relevant documents with new version information, as obtained from
the previous command. At the very least this includes changes to:
- ``docs/conf.py``
- ``usage.rst``
27. Show the changes before making a commit::
git diff docs/
28. Commit the changes::
git add docs/
git commits -m "$ISSUE: Creating maintenance branch for release $NEW_VERSION."
29. Push the maintenance branch::
git push origin "${NEW_VERSION%.*}"
30. Switch back to the master branch::
git checkout master
31. Delete the local branch::
git branch -d "${ISSUE,,}"
32. Mark issue as resolved in the issue tracker.
33. Release the version via release center in the issue tracker.
34. Archive all other releases.
Releasing new patch version
---------------------------
New patch releases are based off of the specific maintenance branch ``HEAD``.
When releasing a new patch release, procedure is as follows:
1. Verify that there are no outstanding issues blocking the release.
2. Switch to the project Python virtual environment::
workon majic-ansible-roles
3. Set the new version and issuer associated with making the release::
NEW_VERSION="MAJOR.MINOR.PATCH"
ISSUE="MAR-NUMBER"
4. Make sure you are on the maintenance branch for that version::
git checkout "${NEW_VERSION%.*}"
5. Extract current version::
CURRENT_VERSION=$(grep '^version = ' docs/conf.py | sed -e "s/^version = '//;s/'$//")
6. Double-check what the associated issues is, what the current version string
is, and what the release version will be::
echo "[$ISSUE] $CURRENT_VERSION -> $NEW_VERSION"
7. Create issue branch::
git checkout -b "${ISSUE,,}"
8. Verify that documentation builds and looks correct::
(cd docs/; make clean html; firefox _build/html/index.html)
9. Test all roles using `Molecule <https://molecule.readthedocs.io/>`_ to make
sure no regressions were introduced.
10. Test deployment of test site from scratch to make sure all roles behave
correctly.
11. Add release notes to file ``docs/releasenotes.rst``. Release notes template
should be as follows::
VERSION
-------
GENERAL DESCRIPTION
Bug-fixes:
* ``ROLE`` role
* BUG-FIX DESCRIPTION
12. Clean-up the documentation build, and check what files need to be updated::
(cd docs; make clean; grep -r "${CURRENT_VERSION/./\\.}" .)
13. Update all relevant documents with new version information, as obtained from
the previous command. At the very least this includes changes to:
- ``docs/conf.py``
- ``usage.rst``
14. Ensure documentation builds correctly::
(cd docs/; make clean html)
15. Show the changes before making a commit::
git diff docs/
16. Commit the changes::
git add docs/
git commits -m "$ISSUE: Preparing for release $NEW_VERSION."
17. Create annotated and signed Git tag::
git tag --sign -a "$NEW_VERSION" -m "RELEASE DESCRIPTION"
18. Clean-up the documentation build, check what files need to be switched back
to maintenance version, and determine maintenance version::
(cd docs; make clean; grep -r "${NEW_VERSION/./\\.}" .)
echo "${NEW_VERSION%.*}-maint"
19. Update all relevant documents with maintenance version information, as
obtained from the previous command. At the very least this includes changes
to:
- ``docs/conf.py``
- ``usage.rst``
20. Show the changes before committing them::
git diff docs/
21. Commit the changes::
git add docs/
git commits -m "$ISSUE: Bumping version to ${NEW_VERSION%.*}-maint (switching back to maintenance)."
22. Verify GnuPG signatures::
git gpgcheck
git verify-tag "$NEW_VERSION"
23. Merge changes back into the maintenance branch::
git checkout "${NEW_VERSION%.*}"
git merge "${ISSUE,,}"
24. Push the tag and changes to mainteance branch::
git push
git push origin "${NEW_VERSION}"
25. Delete the local branch::
git branch -d "${ISSUE,,}"
26. Switch back to the master branch::
git checkout master
27. Mark issue as resolved in the issue tracker.
28. Release the version via release center in the issue tracker.
29. Archive all old patch releases with the same major and minor number as new
release version.
|