-
Notifications
You must be signed in to change notification settings - Fork 48
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Matt Marshall
committed
Jan 31, 2024
1 parent
c9e1d98
commit 7fbd5df
Showing
1 changed file
with
13 additions
and
40 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,54 +1,27 @@ | ||
| Specification Governance | ||
| ========================= | ||
|
|
||
| Open Referral is an open community of practice – anyone who shares our vision and values is welcome. Our network (which includes human service referral providers, government officials, academics, vendors, community leaders, etc) is primarily assembled in our [Community Forum](https://forum.openreferral.org). We also have a [Slack team](https://openreferral.org/get-involved/join-our-slack-team/), and discuss technical issues in [Github](https://github.com/openreferral). | ||
| Open Referral is the steward of HSDS. Open Referral's role is to facilitate and oversee appropriate maintenance and development of HSDS to ensure that it meets the needs of its users. | ||
|
|
||
| Though we are an international initiative, our subject is primarily local and therefore much of the work in our initiative is done locally. This means our decision-making processes are distributed – from **_global_** (as an open community of practice, developing a common standard, collateral materials, open source tools, etc) to **_local_** (as a set of place-based pilot projects led by stakeholders in a given geographical region) and **_sectoral_** (with projects in specific subdomains like legal aid, etc). We operate _iteratively_, with regular opportunities to reflect, change, and grow. | ||
| Open Referral develops HSDS through facilitating transparent and consensus-based cycles which result in agreed upon technical changes to the specification. | ||
|
|
||
| **Core team** facilitates alignment and supports activities across the Open Referral network. | ||
| ## Versioning and Upgrade Process | ||
|
|
||
| At a 'global' level, Open Referral consists of technical and institutional leadership. Core team members a) set the agenda for public discussions; b) oversee accountable administration of any grant funding or other resources in the Open Referral Initiative’s control; and c) make decisions in any instances in which the community cannot reach rough consensus. | ||
| When there is sufficient need and resources, Open Referral announces a development cycle, initiates a Technical Working Group, and elicits contributions from the community to set the agenda. The Technical Working Group works alongside the Technical Steward — an appointed member of the Open Referral Core Team — through various channels to provide input and synthesize specific proposed changes to the specification. The Technical Steward then takes all proposed changes that have *rough consensus* (i.e. proposals with no objections and which most people support) and codifies them into a proposal for a version upgrade which is shared with the community with a Request for Comment. | ||
|
|
||
| **Workgroups** of designated leads who advise on design, implementation and governance. | ||
| The Technical Steward receives additional input from the community during this period which may result in more meetings of the Technical Working Group if it becomes necessary to seek additional consensus. Upon achieving consent from the community around a proposed upgrade, the Technical Steward implements the changes to the specification, documentation, and guidance. | ||
|
|
||
| Workgroups may be formed by any set of members to operate in accordance with the Initiative’s values and principles, and are empowered to make proposals subject to [rough consensus](https://en.wikipedia.org/wiki/Rough_consensus) of the Initiative’s community. Workgroups can consist of at least two community members who agree to collaborate on a stated objective such as the development of Open Referral’s data specifications, implementation guidance, tooling, the governance model for Open Referral itself, etc. Workgroups should include at least one **Subject Matter Expert** to represent users’ needs, and at least one **Lead Facilitator** to be accountable for coordinating activities including setting agendas and taking detailed notes – all of which is expected to be reported on in our regular Assemblies and/or shared in [Open Referral’s community forum](https://forum.openreferral.org/) with appropriate notice. Additional Workgroup members can be nominated by the community (including self-nominations by community members) and/or invited by core team members. | ||
| ### Versions | ||
|
|
||
| Workgroups should demonstrate that aspects of any proposal put forth are directly informed by perspectives and interests expressed by representatives of Open Referral’s [primary beneficiary groups](./users-and-personas) – and are expected to field and respond accordingly to any such feedback received externally. In instances where rough consensus cannot be attained, even after parties have put forth and evaluated alternative proposals and feedback from lead stakeholders of pilot projects has been solicited, Core Team leads reserve the right to make decisions (and will appropriately document the rationale for decisions and ensure the result of those decisions are subject to subsequent evaluation and possible revision). | ||
| HSDS uses [Semantic Versioning](https://semver.org/) to distinguish between different versions of the standard in the format of `MAJOR.MINOR.PATCH`. | ||
|
|
||
| **Technical Standups and Community Assemblies** – In semi-regular meetings open to all members of the community, we facilitate alignment around the mission of the Initiative. | ||
| * MAJOR versions introduce backwards compatible changes | ||
| * MINOR versions introduce new features or functionality in a backwards compatible manner | ||
| * PATCH versions make backwards-compatible bugfixes | ||
|
|
||
| Leadership and technical implementers convene monthly at brief Technical Standups. At semi-regular Assemblies, all are welcome to discuss issues of interest to the commnunity as a whole. Anyone can [join the Forum](https://forum.openreferral.org/) and request to be added to the calendar for these meetings. | ||
| If a change is backwards compatible it means that data published using an earlier version still meets the requirements of the standard. For example data published using HSDS version `3.0` would be compatible with HSDS version `3.1`. Similarly, tools operating using HSDS `3.1` should not encounter problems with HSDS `3.0` data. | ||
|
|
||
| **Summits** | ||
| We also host quasi-annual Summits (longer open meetings) in which we convene share, learn, deliberate, and generate proposals. Summits are not decision-making events, but are critical opportunities for sharing knowledge, building relationships, and setting the agenda for future development. These events can generate and prioritize “user stories,” feature backlogs, and possible courses of action to meet the needs expressed by those user stories. ([See this report back from the inaugural workshop.](https://docs.google.com/document/d/1kivG6TTw1LKhJRAQHeqH7fTIxZZaDojXRRBYEd_ltWw/edit#)) | ||
| If a change is not backwards compatible it may mean that data published using an earlier version will no longer meet the requirements. Not all HSDS publications use all parts of the standard, so it is possible that some data may still be conformant to a newer MAJOR version but it is not guaranteed. | ||
|
|
||
| **Local pilots** implementing data exchanges, evaluating specs, planning for the future. | ||
| You can see a list of all the version upgrades in HSDS by reviewing our [changelog](../hsds/changelog) | ||
|
|
||
| Open Referral focuses much of our work in local pilot projects. In pilots, project stakeholders collaborate to promote access to up-to-date resource directory data in their communities, by using Open Referral’s data exchange specifications to share resource directory data among existing and/or emerging systems. In return, stakeholders can receive facilitation, technical solutions and support, and other kinds of capacity-building when possible, helpful, and appropriate. Feedback from such stakeholders shapes the ongoing evolution of Open Referral. | ||
|
|
||
| Pilot projects’ objectives include short-term demonstrations of the value of open and interoperable resource directory systems, and strategic plans for long-term sustainability of such systems. Local pilot projects should consist of **_teams_**, anchored around **_lead_ _stakeholders_** (see below) who will be represented by some **_leadership structure_** (a ‘table’ or ‘committee,’ etc) – and ideally supported by some core-coordinating capacity of their own (sometimes called [a ‘backbone’](https://www.collectiveimpactforum.org/resources/value-backbone-organizations-collective-impact) as in the Collective Impact coalition model). Pilot projects might also be supported by **_partners_**, i.e., organizations that provide material support, technical assistance and/or other in-kind resources – such as philanthropic funders, contracting agencies, civic technology networks, software vendors, etc., who can help with implementation, if not decision-making. | ||
|
|
||
| **Stakeholders** include any intended beneficiary of Open Referral’s work, as described by our [User Personas documentation](./users-and-personas). (These broad types of beneficiary user groups consist of: help-seekers, help providers, data administrators, and data analysts.) | ||
|
|
||
| Practically, most stakeholder groups are represented in Open Referral by the organizations that serve them (service/referral providers, technology vendors). | ||
|
|
||
| **Lead stakeholders** are voluntary representatives of specific stakeholder groups who commit to the design, implementation, and/or evaluation of Open Referral’s protocols and products through resource data exchanges and associated projects – typically in the context of pilot projects. | ||
|
|
||
| Lead stakeholders’ input is prioritized through all phases of Open Referral’s activities; in instances when Open Referral needs more insight to make a decision, we engage with lead stakeholders to solicit relevant feedback from their stakeholder communities. | ||
|
|
||
| ## Get Involved | ||
|
|
||
| You can contribute to the development of these protocols in several ways: | ||
|
|
||
| * **Add annotations to this documentation site using hypothes.is** - hypothes.is is an annotation service that is embedded in this site. (See the buttons in the top-right of this page.) Just highlight any text, and then use the pop-up box to add your comments. You will need to sign-up for a free account with [hypothes.is](https://hypothes.is/). | ||
|
|
||
| * Add a new issue or [engage with an existing issue on GitHub](https://github.com/openreferral/specification/issues/). We use this issue tracker to schedule all formal updates to the specification. Anyone can view and search the issues already raised. You will need to sign up for a free GitHub account to comment or create issues. | ||
|
|
||
| * Join our [community forum](https://groups.google.com/forum/#!forum/openreferral) where discussions around the specification are encouraged. | ||
|
|
||
| * Request office hours. Upon request, the Open Referral leadership will convene to discuss any issues that participants bring up. Email [info@openreferral.org](mailto:info@openreferral.org) to request an invite. | ||
|
|
||
|
|
||
| ## Roadmap | ||
|
|
||
| You can find upcoming milestones and issues on our development roadmap through the [specification's issue tracker](https://github.com/openreferral/specification/milestones) |