Releases

Dispatch Releases

Dispatch is release roughly weekly. It is currently a human driven event, and this document records the process of cutting a new release, as well as on-going book-keeping to help manage change.

Schedule

Version	Release Engineer
0.1.18	Russell Jew
0.1.19	Zimeng Yang
0.1.20	Berndt Jung
0.1.21	Nick Tenczar
0.1.22	Ivan Mikushin
0.1.23	Karol Stepniewski
0.1.24	Sabari Murugesan
...	repeat

Ongoing Development

The following items refer to tasks which are part of ongoing development, but will play into the release process.

CHANGELOG.md

As part of daily on-going development, developers are expected to update the CHANGELOG.md file at the root of the dispatch repository. Changes/features should be added to top of the document in the unreleased section. It is up to everyone to make sure this is up-to-date. Code reviewers should not approve changes which are not recorded in the CHANGELOG.md. While not all changes need to go into release notes (and therefore the CHANGELOG.md), it's never a bad idea to add your change anyway.

Docs

Documentation should continuously be updated as features and changes are added to the code. The documentation is built out of the gh-pages branch, as opposed to master. Therefore, developers should update the documentation in master as the features are added, then upon release the gh-pages branch is updated so that the published documentation always matches the release.

Release Process

Create release notes

The release notes for each release are reflected as "posts". Add a new file in the docs/_posts/ directory. The file should follow the naming convention <year>-<month>-<day>-v<major>-<minor>-<patch>-release.md (e.g. 2018-06-06-v0-1-16-release.md).

The contents of the file should be built from the CHANGELOG.md, however simply cutting and pasting is probably not sufficient. The release notes should be clear and show example usage where appropriate. They are intended to be customer/user facing.

Each post should contain the following begin with the following (substituting release specific info):

---
layout: post
title: "v0.1.16 Dispatch Release"
year: 2018
---

# v0.1.16 Dispatch Release

[Download v0.1.16](https://github.com/vmware/dispatch/releases/tag/v0.1.16)

Beyond this, the release notes should have headings for each change/feature. See existing posts for examples, and try to follow patterns to create consistent release notes.

Update the CHANGELOG.md

1. Update the Unreleased heading to reflect the current release (follow the pattern).

2. Add a new Unreleased heading (as before) with an updated git compare.

Submit PR

PR should include both the updates to the CHANGELOG.md and the new post. Add the run-e2e tag to ensure that the release passes e2e before we actually create the release artifacts.

Trigger Release

1. Go to the dispatch-release CI job (you will need to login).

2. Open the "patch" and click the "+" to initiate a release.

Update published docs

Documentation is served out of the gh-pages branch. This branch has docs as the root dir, therefore copying over the files is not very straightforward. A script has been created to make this easy though:

./scripts/update-docs.sh [version]

The updates should be live within a minute or so.