Supporting explicit branches

[bethesque]

Tags have traditionally been used to represent git branches and deployment stages/environments in the Pact Broker. While tags are extremely flexible and do technically support our workflows, they are somewhat abstract and cognitively harder to understand than having explicit "branch" and "deployment environment" supported as top level concepts.

I have recently added a branch property to the version resource that will allow us to reference versions and pacts by "latest from branch X' in URLs and consumer version selectors. eg.

/pacts/provider/{provider}/consumer/{consumer}/branch/{branch}/latest (this URL is not implemented as of 4 Feb 2020, but will be soon) and {"branch": "main", latest: true}, {"branch": "feat/x", latest: true} (the consumer version selector support is done, but not released as of 4 Feb 2020).

WIP and pending pacts will support the calculations based on the consumer/provider branches where they are provided, and fall back to tags when not.

Technical info:

• There's now an endpoint to create a version with a branch and a build URL

   PUT http://broker/pacticipants/Bar/versions/1e70030c6579915e5ff56b107a0fd25cf5df7464
    {
      "branch": "main",
      "buildUrl": "http://ci.mydomain/my-job/1"
    }
  

• Publishing pacts and verifications should now support a "branch" property, and the client libraries should all make the above call before creating the tags (I haven't made an "all in one" call for the version and the tags yet).
• When calling the 'pacts for verification' API
  • the consumer version selectors now support branch and fallbackBranch
  • there is an extra providerVersionBranch property
  • If a provider version branch AND tags are specified, the branch is used in preference to the tags when calculating the "work in progress" pacts
  • If only provider version tags are specified, it works the way it currently does
  • When calculating which pacts are WIP, both the "latest for each tag" and "latest for branch" are considered.
• There is a pb:pacticipant-version relation in the index now which should be used:
  • to detect whether or not the broker version supports creating a pacticipant version by PUT, and by extension, whether or not the branch property is supported (please raise/print a helpful error if the user tries to configure a branch when it is not supported)
  • to actually create the pacticipant version

Feature request: https://pact.canny.io/feature-requests/p/support-explicit-branches-and-stages
PR: #371

[solarmosaic-kflorence]

@bethesque I am assuming under the hood "branch" will still just be a normal tag, right? Also what is fallbackBranch for?

[bethesque]

The branch is a String property on the version resource rather than being a collection of objects with a String name that belong to the version (as the tags are). It will support the same features that a tag does though (ie. allow us to identify particular version(s) by a known name).

[bethesque]

The fallbackBranch is for the same thing as the fallbackTag documented here: https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors/#using-a-fallback-tag-for-coordinated-branch-development

[solarmosaic-kflorence]

Ah, I see. From a user perspective, this seems like a win. From a maintenance perspective, it does add extra complexity, especially since the branch is a new concept in code, and not just a new way of specifying/using a tag.

[YOU54F]

@YOU54F just tagging in so I can track this