What is the process for deprecating a hook?

[mattvarghese]

Do we have a process for deprecating an existing hook? Is this necessary? Is this something that should be added to the maturity model in #195?

[isaacvetter]

Great issue, Matt!

It's increasingly evident that we need to figure this out. It's tough because more mature hooks should be harder to deprecate than less mature hooks. At least we've got a solid, albeit untested Hook Maturity Model.

What about this?

Maturity Level	title	process for deprecation
0	Draft	The hooks has not yet been published, deprecation is entirely up to the author.
1	Submitted	The hook has not yet been published, deprecation is entirely up to the author and is done by simply reverting the pull request.
2	Tested	The hook author must now take into account the needs and opinions of the implementers. Deprecation requires the author, a CDS client and an independent CDS service who had tested the hook to agree to its deprecation. The author MUST submit a github pull request updating the hook's maturity to Deprecated and removing the hook definition from the published menu of hooks. For posterity, the hook definition should still be available at its previous url. The github pull request defining the hook is approved and published.
3	Considered	Same as 2- Tested.
4	Documented	The above and ... the hook definition must include the reason for deprecation and document any potential replacement hooks. Community feedback is solicited on the zulip CDS Hooks stream. The hook is removed from the CDS Hooks sandbox.
5	Mature	The above and ... An HL7 working group ballots the hook deprecation at the HL7 STU level.

[brynrhodes]

@isaacvetter , this looks great, thank you for putting this together! The only part I'm not sure about is what it looks like to ballot a hook deprecation, but that might be because it's also not entirely clear what it looks like to ballot a hook definition.

[mattvarghese]

@isaacvetter - you mention

The author MUST submit a github pull request updating the hook's maturity to Deprecated

What does updating the hook's maturity level to Deprecated mean?
Is Deprecated therefore a new maturity level to be added to the maturity levels table?
If yes, what should it's numeric value be? (negative 1? 99?)

Also, in light of @brynrhodes comment, were you meaning the vote we had on Wednesday to be "ballot," or is that something else that needs to yet happen (sorry if this is a naive question from my ignorance of HL7 balloting processes)?

[mattvarghese]

Hey folks, while we debate on the process of deprecating the hook etc, can we please have an interim banner / notice on the medication-prescribe and order-review hooks saying these hooks have been deprecated in favor of the order-select and order-sign hooks? And either have the order-select and order-sign hooks be published speedily, or maybe these warnings can point to the pull requests for the new hooks in the interim?