Supporting explicit deployments

[bethesque]

Tags are currently used to represent branches and stages. They are very flexible and non-prescriptive in order to support as many different organisations' workflows as possible, but some people find the flexibility confusing and might prefer a more prescriptive model.

I have started work on supporting a resource model that represents deployments of pacticipant versions to environments. The first PR to create environment resources is here.

I am planning a CLI command that would replace the current pact-broker create-version-tag --tag ${stage} after a deployment with something like:

pact-broker record-deployment --pacticipant PACTICIPANT --version VERSION --environment ENVIRONMENT

This would make a new "deployment" resource with the pacticipant/version/environment relationships.

The can-i-deploy command would modified to support an explicit environment:

can-i-deploy --pacticipant PACTICIPANT --version VERSION --to-environment ENVIRONMENT

Some applications only have one version deployed in them at a time (eg. APIs) and some have multiple (eg. mobile consumers, or environments where A/B releases are performed). I would like a way to flag whether the operation should mark the previous deployment as ended or not (ie. does this deployment mean that the previous deployment has ended, or is it in addition/in parallel to the previous one). By default, it would be considered to end the previous deployment. Marking previous deployments as ended would allow us to easily know what versions of all applications are currently in a particular environment, and remove the need for the --to-all customisation in the can-i-deploy command when mobile consumers are involved.

The flag I had suggested to toggle between "this deployment replaces the previous one" and "this is in addition to the previous one" was --end-previous-deployment, however, the initial feedback was that this was unclear. I think that the term "deployment" was being understood to mean "the time between starting the deployment process and the application being deployed" rather than "the time that the application is deployed/running in a particular environment". Happy to take thoughts on whether there are better terms to use than "deployment", and on any of the other ideas I've mentioned above.

[bethesque]

What is the noun that means "a specific version of an application running in a specific environment for a period of time that starts when it is deployed, and ends when it is undeployed (ie. when the next version is deployed)".

"instance" has been suggested.

pact-broker create-pacticipant-version-instance --pacticipant Foo --version 1 --environment production --end-previous-instance ???

[TimothyJones]

If I am understanding the meaning correctly, I think it should fit in the sentence:

The [noun] at 2pm tuesday afternoon was v1.2.3

For me, most of the proposed names above wouldn't fit in that sentence. What about deployedVersion or deployment?

pact-broker create-pacticipant-deployed-version --pacticipant Foo --version 1 --environment production --end-previous-deployed-version

pact-broker create-pacticipant-deployment --pacticipant Foo --version 1 --environment production --end-previous-deployment

pact-broker create-pacticipant-deployment-version --pacticipant Foo --version 1 --environment production --end-previous-deployment-version

(end previous should probably be implied, I reckon - with the ability to cancel it with --dont-end-previous or similar)

[bethesque]

(end previous should probably be implied, I reckon - with the ability to cancel it with --dont-end-previous or similar)

Yes, agreed. Most of the time, you're not deploying a mobile consumer.

Having chatted with Matt, I think I'm going to separate the CLI term from the API term and have the CLI use the "business domain" terminology for what has just happened:

pact-broker record-deployment --pacticipant Foo --version 1 --environment production [--no-replace-previous]

And have the API resource model the more technical "deployed version"

/pacticipants/Foo/deployed-versions/environment/production/latest <-- used to get the one that you're "replacing"
/environments/production/deployed-versions/current <- what is currently deployed to "production"

[solarmosaic-kflorence]

I think "deployment" is a proper noun for that. create-pacticipant-deployment 👍 I also like "replace" as a verb signifying when the previous deployment is ending and a new one is going out, the new deployment is replacing the old one. If it's a deployment that runs alongside the old one instead of replacing it, you could go with "update instead of "create", e.g. update-pacticipant-deployment.

[bethesque]

@solarmosaic-kflorence I've actually finished designing this now. I haven't released it officially, but the docs are available here https://docs.pact.io/pact_broker/recording_deployments_and_releases

[solarmosaic-kflorence]

Nice, makes sense to me.

[bethesque]

The record deployment and release APIs are now done and documented here. https://docs.pact.io/pact_broker/recording_deployments_and_releases

The only thing I've got to finish before its official release is the undeploy/end support api.