# HG changeset patch # User Branko Majic # Date 2017-12-20 13:21:09 # Node ID a5fb837d1923a5ca16691176d94e5357366ffc36 # Parent 623e0f69741181c3f6d16a6814c326367f8cc783 CONNT-29: Implemented initial set of release procedures: - Replaced versioning on default branch tip to "dev". - Updated the release notes to include information about changes made since version 0.2. - Added initial set of release procedures, covering versioning schema, instructions on writing release notes, release issue template, backporting of fixes, releasing new versions. diff --git a/docs/conf.py b/docs/conf.py --- a/docs/conf.py +++ b/docs/conf.py @@ -60,7 +60,7 @@ copyright = u'2013, Branko Majic' # built documents. # # The short X.Y version. -version = '0.2-dev' +version = 'dev' # The full version, including alpha/beta/rc tags. release = version diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -70,6 +70,7 @@ Contents quickstart usage development + releaseprocedures releasenotes diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -11,6 +11,33 @@ Release Notes ============= + +dev +--- + +Breaking changes: + +* Package now has hard dependency on more specific versions of + requirements in order to ensure it is not used with incompatible + variants (for example, Django has been fixated to version + 1.5.x). This could cause some issues if application is used with + newer Django versions etc. + [ `CONNT-28 `_ ] + +New features/improvements: + +* A lot of cleanup was performed to make it easier to handle + development process etc. These are mostly internal changes, except + for small documentation fixes. + [ `CONNT-28 `_ ] + +Bug-fixes: + +* Documentation links have been updated to point to new Read The Docs + domain. + [ `CONNT-27 `_ ] + + 0.2 --- @@ -31,6 +58,7 @@ Bug fixes: * Generates valid XHTML5 code now. [ `CONNT-24 `_ ] + 0.1 --- diff --git a/docs/releaseprocedures.rst b/docs/releaseprocedures.rst new file mode 100644 --- /dev/null +++ b/docs/releaseprocedures.rst @@ -0,0 +1,309 @@ +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. +- Writing release notes. +- Release issue template. + + +Versioning schema +----------------- + +*Django Conntrackt* project employs `semantic versioning +`_ 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 *Django Conntrackt* 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 *Django Conntrackt*. +- 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, *Django Conntrackt* employs a specific +nomenclature for naming the branches: + +- All new development and bug-fixing uses ``default`` branch as the base. +- 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). + + +Writing release notes +--------------------- + +Release notes should be updated in relevant branches as the issues are +getting resolved. You can use the following template when filling-up +the release notes:: + + VERSION + ------- + + GENERAL DESCRIPTION + + Breaking changes: + + * DESCRIPTION [ `CONNT-NUMBER `_ ] + + New features/improvements: + + * DESCRIPTION [ `CONNT-NUMBER `_ ] + + Bug-fixes: + + * DESCRIPTION [ `CONNT-NUMBER `_ ] + + +Release issue template +---------------------- + +In order to make life easier, the following template can be used when +creating the issue for a release in the issue tracker: + +- Set *subject* to ``Release version MAJOR.MINOR.PATCH``. +- Set *description* to:: + + Release version MAJOR.MINOR.PATCH. Release should be done + according to release procedures outlined in offline documentation. + + +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 + `_. 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 (using graft if + possible) the fix into maintenace branch. Make sure to reword the + commit message (to reference the backport issue) . + + +Releasing new version +--------------------- + +The following procedure is applicable to both major/minor and patch +releases, with any relevant differences pointed out in the individual +steps. + +Perform the following steps in order to release a new version: + +1. Verify that there are no outstanding issues blocking the release. + +2. Prepare release environment: + + 1. Switch to the project Python virtual environment:: + + workon conntrackt + + 2. Set release version, and set issue associated with making the + release:: + + NEW_VERSION="MAJOR.MINOR.PATCH" + ISSUE="CONNT-NUMBER" + BRANCH="${NEW_VERSION%.*}" + + 3. Verify the information has been set correctly:: + + echo "[$ISSUE] $BRANCH -> $NEW_VERSION" + +3. If this is a new major/minor release, prepare the maintenance + branch: + + .. warning:: + Make sure **not** to run these steps when making a patch release! + + 1. Create the maintenance branch:: + + hg branch "$BRANCH" + + 2. Update versioning information in documentation and setup + script:: + + sed -i -e "s/^version = .*/version = '${BRANCH}-maint'/" docs/conf.py + sed -i -e "s/^ version=.*/ version='${BRANCH}-maint',/" setup.py + sed -i -e "s/^dev$/${BRANCH}-maint/" docs/releasenotes.rst + + 3. Fix the title underline for version string in + ``docs/releasenotes.rst``. + + 4. Show differences before committing:: + + hg diff + + 5. Commit the changes:: + + hg commit -m "$ISSUE: Creating maintenance branch ${BRANCH}." + +4. Ensure you are on the maintenance branch: + + 1. Switch to maintenance branch:: + + hg update "$BRANCH" + + 2. Verify the switch:: + + hg branch + +5. Create release commit: + + .. warning:: + Make sure not to push changes at this point, since the relesae + commit must be tested first. + + 1. Update versioning information in documentation and setup + script:: + + sed -i -e "s/^version = .*/version = '${VERSION}'/" docs/conf.py + sed -i -e "s/^ version=.*/ version='${VERSION}',/" setup.py + sed -i -e "s/^${BRANCH}-maint$/${VERSION}/" docs/releasenotes.rst + + 2. Fix the title underline for version string in + ``docs/releasenotes.rst``. + + 3. Show differences before committing:: + + hg diff + + 4. Commit the changes:: + + hg commit -m "$ISSUE: Releasing version ${VERSION}." + +6. Verify release behaves as expected: + + 1. Verify that documentation builds and looks correct:: + + (cd docs/; make clean html; firefox _build/html/index.html) + + 2. Run tests:: + + (cd testproject; python manage.py test) + + 3. Build source distribution package, verifying no errors are + reported:: + + python setup.py sdist + + 4. Test the quick-start instructions to ensure they are still + applicable. When installing the package, make sure to use the + source distribution package from previous step. + + 5. Correct any outstanding issues prior to proceeding further, and + repeat the test cycle for any sort of change, ammending the + previous commit if possible (instead of creating new ones). + +7. Push release to PyPI: + + 1. Tag the release:: + + hg tag "$VERSION" + + 2. Push the (tested) built source distribution:: + + python setup.py upload + +8. Clean-up the maintenance branch: + + 1. Start a new release notes section in ``docs/releasenotes.rst``:: + + sed "/^Release Notes$/{N;s/$/\n\n\n${BRANCH-maint}\n-----------/}" docs/releasenotes.rst + + 2. Update versioning information in documentation and setup + script:: + + sed -i -e "s/^version = .*/version = '${BRANCH}-maint'/" docs/conf.py + sed -i -e "s/^ version=.*/ version='${BRANC}-maint',/" setup.py + + 3. Fix the title underline for version string in + ``docs/releasenotes.rst``. + + 4. Show differences before committing:: + + hg diff + + 5. Commit the changes:: + + hg commit -m "$ISSUE: Bumping version back maintenance." + +9. Clean-up the default branch if you have just released a new + major/minor version: + + .. warning:: + Make sure **not** to run these steps when making a patch release! + + 1. Switch to default development branch:: + + hg update default + + 2. Verify the switch:: + + hg branch + + 3. Update versioning information in release notes:: + + sed -i -e "s/^dev$/${BRANCH}-maint/" docs/releasenotes.rst + + 4. Start a new release notes section in ``docs/releasenotes.rst``:: + + sed "/^Release Notes$/{N;s/$/\n\n\n$dev\n---/}" docs/releasenotes.rst + + 5. Fix the title underlines for version strings in + ``docs/releasenotes.rst``. + + 6. Show differences before committing:: + + hg diff + + 7. Commit the changes:: + + hg commit -m "$ISSUE: Starting new release notes in default development branch." + +10. Wrap-up changes on external services: + + 1. Push the changes to upstream repository and its mirror:: + + hg push + hg push bitbucket + + 2. Go to `Read the Docs administrative pages + `_, and + add the build for new version, retiring any unsupported + versions along the way. + + 3. Mark issue as resolved in the issue tracker. + + 4. Release the version via release center in the issue tracker. + + 5. Archive all other releases. diff --git a/setup.py b/setup.py --- a/setup.py +++ b/setup.py @@ -37,7 +37,7 @@ os.chdir(os.path.normpath(os.path.join(o setup( name='django-conntrackt', - version='0.2-dev', + version='dev', packages=find_packages(exclude=["testproject", "testproject.*"]), include_package_data=True, license='GPLv3+',