HSDS Governance: Versioning, Upgrade process etc

[dan-odsc]

• There does not appear to be a formal versioning mechanism for the HSDS standard or the Reference material – Please correct me if I'm wrong, but I cannot find any formal adoption of a versioning mechanism for either HSDS or the Reference material (docs). I believe we've used semantic versioning up to now, but we've never formalised this. I believe that this should be written down in a way that encompasses us making MAJOR, MINOR, and PATCH level updates to both the schemas and the normative documentation.

• There does not appear to be a formal or semi-formal governance process for HSDS – this underpins the above. We've had some positive and clear discussions in meetings about the Governance structure of HSDS, how version upgrades happen (e.g. calling a working group) and what happens inbetween the times where a working group is active (such as now). We could write this down, and tie this to the versioning process to say "This is what will happen when we do a MAJOR uprade, this is what checks are done when we do a MINOR or a PATCH" etc. This would also allow us to specify that particular sections of the docs are covered by the governance process (i.e. the Normative Reference material), so that changes to these go through particular processes and result in clear version changes. For example, changing the structure of a page or correcting some spelling could be classed as a PATCH change, and require approval from Greg or the Technical stewards.

• The docs may be trying to do/be too much – The docs contain Normative Reference Material for HSDS, "Not normative" Guidance material for HSDS, a comments system, FAQs and documentation about the Open Referral Initiative. There are lots of ways to integrate this holistically and I'm not saying we need to excise or scrap entire sections, but I think we might benefit from taking a step back and asking the question "What are the docs for?" and streamlining them. At the very least, we can plan for a "user journey" through the docs which integrates all the material at appropriate places.

[dan-odsc]

Related - https://docs.google.com/document/d/1WvDWRhU3pRD_z1JQjDHTvcReP92CVCJWo_DNReOaC3A/edit#heading=h.an4b3pdgh806

[greggish]

I've updated the Openreferral.org website, adding pages with content that previously was either in Google Docs or briefly in the Project Documentation section of our technical docs.

See here: https://openreferral.org/about/organizational-overview/governance-and-participation/

First of all, I think this means we can remove most of the Project Documentation from the technical docs. That section can be renamed from "ABOUT THE OPEN REFERRAL INITIATIVE" to "ABOUT." I think the Types of Use and User Personas should stay, bumped up to the top; then Design Principles; then I think a section on Specification Governance; then Credits. (I am just noticing i don't see a page for License but i am pretty sure we have one? We need one.)

For the Specification Governance I think we can leverage the first three subsections of this page. I think it would make sense to add more specifics about versioning there – what do you propose?

Anything else?

[dan-odsc]

First of all, I think this means we can remove most of the Project Documentation from the technical docs. That section can be renamed from "ABOUT THE OPEN REFERRAL INITIATIVE" to "ABOUT." I think the Types of Use and User Personas should stay, bumped up to the top; then Design Principles; then I think a section on Specification Governance; then Credits.

We will get onto this - sorry for the delay.

(I am just noticing i don't see a page for License but i am pretty sure we have one? We need one.)

@mrshll1001 I thought I saw a section on licensing at some point also? Can you look into this?

For the Specification Governance I think we can leverage the first three subsections of this page. I think it would make sense to add more specifics about versioning there – what do you propose?

Yes, that makes sense in terms of where it will sit. Although, due to the overlap between versioning and governance, versioning, and upgrades it would be good to clarify exactly what you want our input on in regards to this?

Dan

[dan-odsc]

All we have re license is this FAQ:

https://docs.openreferral.org/en/latest/hsds/hsds_faqs.html#what-is-the-licensing-on-this-project

[dan-odsc]

For the Specification Governance I think we can leverage the first three subsections of this page. I think it would make sense to add more specifics about versioning there – what do you propose?`

@greggish I'm wondering if we should hold off on this until the work you and Devin are doing on the governance model has concluded?

Also JTLYK, @matt and I are working on the high-level questions you asked for. They will be ready to share with you on Thursday.

[greggish]

It would be helpful to get from you all a proposed mechanism or set of processes for versioning, including any open questions that you think ought to be addressed through governance.

Meanwhile yes the Specification Governance we can leave as is for now, and expect that one way or another we will have further clarification soon.

[dan-odsc]

👍🏻

On Mon, 22 Jan 2024 at 19:48, Greg Bloom @.***> wrote:

It would be helpful to get from you all a proposed mechanism or set of processes for versioning, including any open questions that you think ought to be addressed through governance.

Meanwhile yes the Specification Governance we can leave as is for now, and expect that one way or another we will have further clarification soon.

— Reply to this email directly, view it on GitHub https://github.com/openreferral/specification/issues/475#issuecomment-1904695781, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4PEV27DHKFPSWVQJCHUQQLYP27BPAVCNFSM6AAAAAA7PZ3VN2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBUGY4TKNZYGE . You are receiving this because you were assigned.Message ID: @.***>

[dan-odsc]

@greggish has updated the Specification Governance Section on the v: refactor-project-documentation branch

@mrshll1001 to review the commit and merge once we're happy.