Page History

...

• User driven
  • Users refers specifically to WMDA member registries (or their delegates) that currently use or intend to use the Match-Connect apisAPIs
  • During the early design and implementation phases of Match-Connect, features will be proposed by the Match-Connect Steering Committee and participating pilot registries
  • Following the pilot phase, all user driven features will be requested via the Match-Connect User Group RFC Process
• Implementation team driven
  • Implementation team refers to the technical staff of the WMDA and their associates that are directly involved in the implementation of the Match-Connect apisAPIs
  • The implementation team may need to include items in a release to resolve defects, improve underlying design, update dependencies / libraries and to keep the software in good, working order

...

Whether user driven or implementation team driven, any proposed inclusions proposed features with user impact and/or those requiring significant internal resources will be logged / summarized in the WMDA Share under the the Match-Connect Release Management page as part of a release candidate package.   In the immediate term, the Match-Connect Steering Committee will assist with determination of impact and effort in order to assign features to a given release candidate.   Each candidate feature will be given a disposition (Approved, Rejected, moved to RFC).  Implementation actions (updating code, updating the semantics, updating swagger, etc) will be recorded on the release candidate page and tracked for completion.  

The implementation team will leverage Azure Dev Ops for more detailed tracking of their software development work.   The Match-Connect Product Owner will take responsibility for ensuring synchronization of feature inclusion into the detailed work items in Azure Dev Ops.

Feature Impact Categorizations

• Minor = cosmetic or wording only
• Moderate =

...

• API change
• Major = significant behavioral change

Example(s) of Candidate Features

The following snapshot is pulled from the MC v1.01 Release Candidate.

Versioning

The semantic versioning scheme will be utilized for Match-Connect releases going forward.  It can be summarized as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backward compatible manner
3. PATCH version when you make backward compatible bug fixes

Release candidates will be tagged according to this strategy both in the WMDA Share, Match-Connect Semantics and Azure Dev Ops.

Following the pilot, we will align the versioning of the semantics with the public versioning of the APIs and keep them in step going forward. In the meantime, a change log (manifest) will be used to tie the versions of the semantics and the APIs together.

Breaking Changes

In API development, a breaking change refers to modifications in the API that are incompatible with the existing version, potentially causing existing users of the API to experience problems unless they adapt their code. These changes typically require clients to make corresponding updates to maintain functionality. Key examples of breaking changes include:

1. Removing or Renaming Endpoints: If an API endpoint is removed or renamed, client applications that rely on that endpoint will fail unless updated.

2. Changing the Behavior of an Endpoint: Altering how an endpoint functions, such as changing its intended effects or outputs, without a corresponding change in the endpoint's name or parameters.

3. Modifying the Request Format: Changes in how data should be sent to the API, like altering the structure of a request body or the type and name of request parameters.

4. Altering the Response Format: Changing the structure or format of the response that the API returns, such as removing, renaming, or changing the type of data fields.

5. Changing Error Codes or Messages: Modifying the error codes or messages returned by the API can affect client application logic that relies on these for handling API errors.

6. Changing Authentication Requirements: Any modifications in the authentication mechanism or its requirements, like changing from basic authentication to OAuth, would be a breaking change.

7. Deprecating Features without a Grace Period: Deprecating or removing features without providing adequate notice or a transition period can disrupt client applications.

8. Changing the Domain or Protocol: Moving the API to a different domain or changing the communication protocol (e.g., from HTTP to HTTPS) without maintaining the old endpoint.

It's crucial for API developers to communicate these changes effectively to users and, where possible, to maintain backward compatibility or provide a transition period to minimize disruption. This often involves versioning the API so that the older version remains operational while clients adapt to the new version.

Release Timing

Breaking or major changes must be coordinated with the community and should only be made on a periodic basis (e.g. once / year).  Minor changes and patches may occur at the discretion of the Match-Connect implementation team, with an aim towards continuous delivery.

Coordination of Major Releases

• WMDA can introduce new versions of the APIs at any time, so long as the existing versions of the APIs still exist
• Then, during a defined period, the community must prepare to receive via the new versions of the APIs
• Once all parties can receive (or at the end of the defined period), any may send using the new versions of the APIs
• Then WMDA may deprecate the old versions of the APIs

@startgantt
<style>
  ganttDiagram {
    task {
		BackGroundColor dodgerblue
		FontColor white
    }
  }
</style>
title Major Releases of Match-Connect APIs (example schedule)
projectscale weekly

project starts 2025-05-15
[i] lasts 1 day
[Community informed of major release (e.g. Spring Mtg)] as [ci] happens at [i]'s end
[ci] displays on same row as [i]

[WMDA develops new APIs] as [WMDA dev] lasts 120 days
[New APIs deployed to test] as [test] happens at [WMDA dev]'s end
[Community preparation, development and testing] as [comm prep] lasts 180 days
[Community ready to receive via new apis (e.g. Fall Mtg)] as [comm rec] happens at [comm prep]'s end
[Deploy] as [prod] lasts 14 days
[prod] starts after [comm rec]'s end
[Community may send using new APIs] as [new] happens at [prod]'s end
[Old / New APIs] as [both] lasts 30 days
[both] starts after [new]'s end
[Old APIs deprecated] as [dep] happens after [both]'s end
[End] happens 270 days after [ci]'s end
@endgantt

Release Notes

Release notes shall be generated coincident with each release of Match-Connect.  Depending upon the audience, these notes may be generated from the release candidate page(s) in WMDA Share OR directly from Azure Dev Ops.  The implementation team will have a change log (manifest) for each release (major / minor / patch).  Release notes may be published for the benefit of end users when there are major changes.