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.

[dan-odsc]

We have two versions of the flow chart:

- One in the docs

• This working version

Task for ODS:

• Cross-reference and consolidate the two
• Draft some supporting documentation to explain what happens in each step. (The flowchart is useful but leaves a lot practical, procedural questions unanswered when it comes to exactly how the committee and ourselves will work together).
• Create some options for how to go about Technical Committee Review.

[dan-odsc]

Create some options for how to go about 'Technical Committee Review.'

In the flowchart, we say this step in the process consist of the following 'Committee and stewards review issue classifications, refine issues and prioritize them for codification.'

Options for how we can go about this:

1. Steward-Driven Prioritisation

Similar to the approach for version 3.1, Technical Stewards would handle issue triage, classification, and prioritisation asynchronously, then share a prioritised list with the Technical Committee for feedback and sign-off. Although this method received positive feedback, some felt it allowed the stewards too much influence.

2. Collaborative Prioritisation

Under this option, Technical Stewards would initially triage and classify issues asynchronously, then collaborate with the Technical Committee in one or more of the following:

• Technical Committee meetings
• Dedicate priority-setting meetings
• Within a dedicated working group

To collectively review and prioritise issues that the stewards would develop into formal proposals.

3. Committee-Driven Prioritisation

With this approach, stewards would triage and classify issues, after which committee members could independently review and prioritise them, determining which issues should proceed to formal proposal. This reflects feedback that the stewards should be guided by a committee actively representing community needs.

Options 2 and 3 would require stewards to format and organise issues clearly to enable committee engagement—for example, summarised issue overviews, thematic tagging, and consistent formatting.

@greggish

I just want to run this by @kathryn-ods tomorrow morning before sharing with the committee ahead of next Wednesday's meeting.