Add the ability to provide "deploy notes"

[halostatue]

We’re happily using sqitch for a few of our projects, but there’s one point that has become a problem for us when we deploy in production-like environments.

We generate a sqitch bundle package with a timestamp, e.g., <schema-name>-20180910145232.tar.gz and deploy based on that timestamp.

It would be nice if we could do something like sqitch deploy -n "Deployed via package 20180910145232" and have this show up in the deploy log somehow/somewhere so that when we show the log we can see what package was used to deploy the latest schema.

[halostatue]

We would still love to see this happen, but it has become a bit less of a problem with a recent addition we made to our packaging process.

We have always tagged our schema releases with timestamp-TIMESTAMP, which matches the deployed package name. We recently added a second part to this so that it is timestamp-TIMESTAMP-CHANGEID where the change id is sqitch plan --format format:%H --reverse --max-count 1 --no-headers --no-pager.

Now, we can check our database status endpoint (which shows us the change IDs) and reverse-track to the first tag with that change ID and we are looking at the packaged bundle that was deployed.

It would be nice if there were a shorter way to get the most recent change ID, but we did get there eventually.

[theory]

Trying to understand the use case here. AFAICT, this is one of the use cases for tags. Have you considered making releases with tag names (or version numbers) rather than timestamps?

[halostatue]

We aren't versioning anything and would at best be using timestamps as tags (e.g., sqitch tag YYYYMMDDhhmmss), but that has additional problems from our perspective. When we merge a PR that has a sqitch change in it, our CI:

1. Sets the timestamp (date +%Y%m%d%H%M%S)
2. Creates a bundle tarball using the timestamp (e.g., sqitch bundle followed by tar cf SCHEMA-$timestamp.tar.gz bundle)
3. Uploads the bundle to S3.
4. Creates a git tag (using gh, no push permission required) for the current HEAD.

The "problem" with sqitch tags is that they don't work well with automated releases like this:

1. Generating the tag modifies the plan
2. The modified plan should be tested
3. The modified plan needs to be committed and pushed back up (we have branch protection on, so an exception would be required)
4. We still would need to do everything else that we have in steps 1–4 but using the tag ID instead of a self-contained timestamp.

We deploy the timestamp-flagged package, and until we hit on using the change ID as part of our git tag, it was hard for us to get a sense of how to back-flag this.

To make sqitch tags work, we would need to change our process to be something more like:

1. Review the changes, merge.
2. Agree that the changes constitute a releasable version.
3. Create a sqitch tag, review, and merge.
4. Automated release would look for a new sqitch tag that does not have a matching git tag and go through the release process above.

[halostatue]

The original request (deploy notes) would allow us to explicitly flag a deploy as coming from a specific built package. This gets us within a small range of packages (usually one, but if we have non-functional changes, a release package still gets built).

[theory]

If you just want something in the plan to indicate a release, but don't want to check it in or change the values in the plan, just a note, you can also append a comment, something like:

printf "# RELEASE %s\n" "$(date +%Y%m%d%H%M%S)" >> sqitch.plan