...
- 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, proposed features with user impact and/or those requiring significant internal resources will be logged in the WMDA Share under 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.
...
- Minor = cosmetic or wording only
- Moderate = api API change
- Major = significant behavioral change
...
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:
...
Following the pilot, we will align the versioning of the semantics with the public versioning of the apis 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.
Release Timing
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:
Removing or Renaming Endpoints: If an API endpoint is removed or renamed, client applications that rely on that endpoint will fail unless updated.
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.
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.
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.
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.
Changing Authentication Requirements: Any modifications in the authentication mechanism or its requirements, like changing from basic authentication to OAuth, would be a breaking change.
Deprecating Features without a Grace Period: Deprecating or removing features without providing adequate notice or a transition period can disrupt client applications.
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 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.
...
| PlantUML Macro |
|---|
@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 |
...