FHIR Chat · docs / PR #115 Add support for versioning the specification · cds hooks/committers

Stream: cds hooks/committers

Topic: docs / PR #115 Add support for versioning the specification

---

Github Notifications (Nov 19 2017 at 17:43):

kpshek opened PR #115
from issues/100-versioning to master

This PR adds support for versioning the CDS Hooks specification. Today, the specification lives at /specification. With this change, it is now at /specification/1.0.

Future versioning can live at similar URLs. Eg:
- /specification/1.1.md
- /specification/2.0.md

This fixes #100

Github Notifications (Nov 19 2017 at 17:43):

kpshek review_requested PR #115

Github Notifications (Nov 19 2017 at 17:43):

kpshek review_requested PR #115

Github Notifications (Nov 19 2017 at 17:43):

kpshek review_requested PR #115

Github Notifications (Nov 19 2017 at 17:43):

kpshek review_requested PR #115

Github Notifications (Nov 20 2017 at 14:31):

isaacvetter commented on PR #115

@kpshek , in 1.0.md, I think that you should add the uuid back in suggestions. Note that the AUC use-case requires tracking an externally recommended suggestion for auditing purposes via a unique identifier.

Github Notifications (Nov 20 2017 at 16:01):

kpshek commented on PR #115

Thanks, this makes sense. Did you consider skipping the dropdown for now?
Just - Specification: 'specification/1.0.md' so link takes you directly to 1.0 page?

@brettmarquard - I did but this isn't possible in mkdocs today. They have a long standing issue logged for this (mkdocs/mkdocs #73).

After some thought, I like the proposed approach here better. This forces everyone to always link to a versioned specification. A common thing I see with the FHIR homepage URL structure is that people often link to the versionless page, not realizing that in the future that will be updated.

Github Notifications (Nov 20 2017 at 16:49):

vadi2 commented on PR #115

Definitely agree, this is a good move to make it explicit.

On Mon, 20 Nov 2017, 5:02 pm Kevin Shekleton, <notifications@github.com>
wrote:

Thanks, this makes sense. Did you consider skipping the dropdown for now?
Just - Specification: 'specification/1.0.md' so link takes you directly
to 1.0 page?

@brettmarquard <https://github.com/brettmarquard> - I did but this isn't
possible in mkdocs today. They have a long standing issue logged for this (mkdocs/mkdocs
#73 <https://github.com/mkdocs/mkdocs/issues/73>).

After some thought, I like the proposed approach here better. This forces
everyone to always link to a versioned specification. A common thing I see
with the FHIR homepage URL structure is that people often link to the
versionless page, not realizing that in the future that will be updated.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<https://github.com/cds-hooks/docs/pull/115#issuecomment-345740454>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AAGxjJUU4nO9QwhKowRzVHDjFhwYDirEks5s4aJhgaJpZM4Qjd1U>
.

Github Notifications (Nov 20 2017 at 19:56):

kpshek edited PR #115
from issues/100-versioning to master

This PR adds support for versioning the CDS Hooks specification. Today, the specification lives at /specification. With this change, it is now at /specification/1.0.

Future versioning can live at similar URLs. Eg:
- /specification/1.1
- /specification/2.0

This fixes #100

Github Notifications (Nov 20 2017 at 19:58):

jmandel commented on PR #115

I'm happy with the explicit treatment. A few notes:

• specification page it's not the only part of the site that might change with different versions. The examples certainly would, and the hooks catalog might. Especially if we have backwards incompatible changes in the future.

• It might be good to be explicit about the current draft status too, like specification-1.0-draft (similar to SNAPSHOT in the maven world).

Github Notifications (Nov 20 2017 at 20:06):

kpshek commented on PR #115

Thanks for the feedback, @jmandel!

specification page it's not the only part of the site that might change with different versions. The examples certainly would, and the hooks catalog might. Especially if we have backwards incompatible changes in the future.

Agreed. My thinking is that we address those changes/pages when we have > 1 version. Given that we won't be "releasing" that content, I didn't think it was a pressing need to address at this point.

It might be good to be explicit about the current draft status too, like specification-1.0-draft (similar to SNAPSHOT in the maven world).

I considered this now but thought that I would just leave it as-is with the note at the top of the page. Once we release 1.0 we'll do this for the next version (eg, 1.1-draft.md)

Github Notifications (Nov 20 2017 at 20:20):

kpshek closed PR #115

---

Last updated: Apr 12 2022 at 19:14 UTC