Balloting and Publishing FHIR content
In FHIR, there are only two mechanisms for publishing content that is based on the FHIR specification: (DH: need to be explicit that this is for 'official' HL7 publishing)
- direct inclusion of content in the FHIR core specification
- publication of a FHIR implementation guide
If an HL7 work group is seeking ballot review or publication of any artifact or collection of artifact that includes FHIR profiles, value sets, code systems, concept maps, logical models or any other structures that are based on the FHIR infrastructure, they will either be publishing that content as part of the FHIR core specification or they will be producing a FHIR implementation guide. The FMG does not permit the balloting or publication of FHIR artifacts except through one of those two mechanisms.
The expectations for work groups doing either of these is described below.
In all cases, the objectives are the same:
- Ensure that the time and energy of the ballot community is respected
- Ensure that guidance to the implementer community is clear
- Ensure that content being published or submitted to ballot review is of high quality
- Ensure that we create specifications we are confident will be adopted by the community
If development of content is funded, project sponsors should be aware of the expectations below and understand that while the FHIR Management Group strives to enable content to progress in a timely fashion, we cannot guarantee that content will progress in accordance with contractual or regulatory deadlines.
These steps apply regardless of how how you're planning to get your content published:
1. Find an HL7 work group to sponsor the content. All content published by HL7 must be sponsored by (and maintained by) a work group. If you're not sure what work group is appropriate, ask on http://chat.fhir.org and the community will make recommendations. If the recommended group(s) are not able/willing to sponsor the content, you can approach the FHIR Management Group for advice.
2. Get your Project Scope Statement (PSS) approved. Your PSS must note an intention to produce FHIR artifacts and must receive approval from the FMG. The deadline for final approval by the TSC of the PSS is one month prior to the WGM before the ballot in which the content is to appear. That generally means that the PSS should be approved by the work group at 8-9 months prior to the opening of the target ballot. Because PSSs require multiple levels of approval, work groups should actively monitor (and nudge) their proposals through the process. They should also be prepared for the the rejection of the original PSS and the need to make significant edits and go through the process again. (I.e. Start on this sooner rather than later and if it's a funded project, be sure sufficient time is allowed.
3. The FMG maintains a web page that lists upcoming ballot deadlines which they update from time to time to reflect changes in process and priorities which vary from cycle to cycle. Work groups should consult this page and monitor the co-chairs and/or FHIR lists for announced changes. These changes will also be announced on the [Announcement] stream on Zulip.
4. Whoever is actually developing the content will require "committer" access to HL7's GitHub repository and will need to set up their development environment in order to build the content This process is described in [a committer].
Inclusion in core
Content included in the core specification might be resources, profiles, value sets, code systems or concept maps. For the latter 3 (the terminology resources), the administrative process is very light: submit a change request to be approved by the responsible work group. If they believe the artifacts are of use internationally, the artifacts are well defined, and the content is appropriate to be maintained by HL7 international, they'll accept the proposals and incorporate the content into the specification.
The core specification is balloted on a schedule determined by the FHIR Management Group and aligned to support the capabilities of both the implementer community and the HL7 content development and ballot review communities. Timelines are also driven by the feedback provided during the ballot process. While projects can communicate their 'desires' to the FHIR Management Group, the FMG cannot guarantee any particular timeline or progress of FHIR core content and will not adjust the timing of ballots to accomodate the needs of any individual project.
For resources and profiles, the process is as follows:
- Have the work group approve a Proposal using the wiki Resource or Profile template and send an email to email@example.com requesting that the proposal be reviewed. The FMG will establish a deadline for this to be received in order to be eligible for ballot as STU. Typically this will be at least 6 weeks before the ballot deadline.
- Be aware that in some cases, the FMG may want to see a draft of a proposed resource or get feedback from other work groups, connectathons and/or the community before approving the scope of a resource. Some resources may appear in one or more publications as "draft" before finally receiving FMG approval if the appropriat scope boundaries to meet the communities needs is unclear.
- Source must be committed to HL7's gForge repository (DH: should this be git?) by at least one WGM prior to the ballot opening, possibly more to be a candidate for STU. (The FMG will announce if the deadline is earlier.)
- In some cases, a work group might commit source to Git prior to submitting a resource or profile proposal. Proposals are required to be submitted (but not necessarily approved) if an artifact is going to appear in a publication though.
- Instructions for introducing a new resource can be found here
- Balloting of the resource/profile will be driven by the FHIR Core ballot schedule as determined by the FMG.
- Progression of the artifact will be governed by the FHIR Maturity Model
- The FMG will determine whether draft artifacts are of sufficient quality and usefulness to be included when publishing a new FHIR release
Publishing an Implementation Guide
Implementation guides can be balloted and published on a separate timeline from the main specification.
Expectations for publishing implementation guides are as follows:
- Source content must be maintained as a project under HL7's GitHub repository.
- The content must publish using HL7's continuous integration build publishing environment
- Guidance for using the IGPublisher is here. This tool evolves frequently and committers should seek advice and guidance on the FHIR committer's stream. Workgroups are *strongly* advised to use one of the frameworks used for other FHIR ballots. eventually a common framework will likely be mandated for all HL7-balloted IGs.
- An IG Proposal must be created and the FMG notified by sending an email to firstname.lastname@example.org. This must be *approved* by FMG prior to submitting the NIB for the implementation guide (so submitting to the FMG should occur at least 3 weeks prior to NIB deadline).
- The CI build must be set up and working correctly on the continuous integration environment with at all artifact types and publishing functionality exercised no later than the HL7 NIB submission deadline.
- "Comment only" ballots will only be supported if the work group has a specific objective for using the 'comment only' ballot that cannot be met with a less formal mechanism such as a peer review or a frozen snapshot published for connectathon purposes. Multiple "comment only" ballots prior to an STU or Normative ballot are strongly discouraged.
- Content should only be submitted to an "STU" ballot if the content is deemed to be "complete and ready to publish". If the work group already knows of changes they plan to make to the STU content after ballot prior to publication or is already planning a second STU ballot, they must seek explicit permission from the FMG to do this. Multiple STU-level ballots prior to publication should be rare.
- Artifacts in an IG cannot be balloted as STU or normative unless the underlying artifact (resource, value set, profile, etc.) already has or is being balloted at the same or a higher level and cannot be published until the underlying artifact has the same or a higher level. I.e. You can't publish a portion of an IG as Normative if it relies on resources that did not pass Normative ballot.
- Additional guidance on IG timelines can be found here