This is the proposed process to be followed for changes that:

  • Use the HL7 IG publisher machinery (whether for FHIR, V2, CDA, Terminology or other content) 
  • Impact one or more of the HL7 maintained templates, including the 'base' template; and/or impact the IG-Publisher in a way that changes what IG authors can (or may) do or what IG readers see
  • Are not considered 'technical corrections' - i.e. a situation where the existing tooling is already clearly expected to behave in a particular way but, because of a bug, is not; where there's a spelling/grammar issue; etc.

This process is DRAFT and has not yet been endorsed by the relevant groups within HL7.

This process will continue to evolve.  Significant changes to the process will occur with oversight of product family management groups and the TSC.

  1. Issue submission & triage
    1. Relevant tools are: IG-Publisher, each of the templates.  Issues can also be submitted seeking improved documentation (for IG authors or IG consumers)
    2. Issues may be identified in a variety of forums (work group discussion, private email, Zulip discussion, etc.) but will only be tracked and managed if submitted as Jira (preferred) or Github tickets.
    3. Issues will be triaged and managed by this FHIR Infrastructure project, with supervision by the various management groups, external contributing bodies, and ultimately the TSC.
      1. This project will be open to all interested participants
    4. This project will consolidate issues that fall into the scope of this process (issues that fall under HL7 authority - i.e. those impacting IGPublisher input or how rendered implementation guides appear) into a single Jira project (tentatively called 'IG-TOOLS').  Content submitted in IG-TOOLS that does not fall under the scope of this project will be propagated into GitHub,
      1. If already raised in a 'specification tracker' Jira, we'll either 'move' the issue (if not ballot related) or create a link from Jira to the IG-TOOLS issue
      2. If we're not sure whether a feature should be specific to HL7 or a particular product family, we'll track it at the most generic template level it could potentially apply to
        1. If issues are created at the 'wrong' level, we'll copy to the proper place, create a link and close the issue
    5. If an issue impacts both publisher and templates, an issue will be put in both places with links between and dependencies clearly described
      1. Similar process will be followed if change will impact other tools (e.g. terminology service, validator, etc.)
    6. During initial triage we will ensure the issue is in the correct repository (Git vs. Jira) and project
    7. Triage may involve seeking more details from the submitter
    8. Once an issue has been reviewed and the problem is clear, we will tag it as ready
  2. (deleted)
  3. Solution Design & Planning
    1. All issues remaining in the IG-TOOLS project will be reviewed and discussed as follows:
    2. Decide on proposed solution
      1. Enhancements to the publisher that do not force changes to how IG content is authored or appears in the published specification (e.g. that require changes to templates in order to manifest) will typically only receive cursory review rather than rigorous discussion and approval.  I.e. No public discussion period or endorsement by product management groups or external bodies will be expected.  The objective of the review that does occur will be to minimize maintenance or architecture concerns
      2. Product directors and the HL7 CTO may have authority to mandate that certain functions must exist in the publisher tooling.  If there is an unresolvable conflict between the requirements of the product directors, they will be resolved by the CTO.
      3. If a change is intended to be surfaced in the base or HL7 templates, then agreement about appearance (i.e. next step) is necessary.
    3. Get agreement from community on proposed solution & priority
      1. Initial review will identify what level of the community is appropriate for the change - where does the benefit lie and is there consensus within the community that the change is desirable. 
        1. By default, we will aim to make changes to the broadest level possible where there is agreed benefit.
        2. Some types of changes (e.g. related to Jira, logos for particular families, etc.) will self-evidently be only relevant to specific communities and will be targeted accordingly
      2. 4 different levels of community
        1. base = 'everyone'
          1. Examples: changes to layout of snapshot or differential tables, changes to metadata summaries for resources, changes to rendering of table of contents
          2. Proposal goes out to IG-templates/Announce stream (or something like that)
          3. Period of time for review & feedback (say 2 weeks)
          4. Then discussed on project call.  If appropriate, revise and re-kick out to community
          5. Once approved and applied, content lives in 'current' release for at least 1 month before being pushed into 'official' release (see step 7 below)
        2. HL7 = 4 management groups and, if disagreement amongst management groups, TSC
          1. Examples: Changes related to Jira integration, changes related to enforcement of TSC-mandated QA rules that aren't shared by affiliates/IHE/etc.
          2. Proposal goes into a discussion area with notifications to each of the relevant management groups seeking approval/feedback
          3. Iterate based on feedback
          4. Require approval from all 4 management groups or blessing of TSC to proceed
            1. Failure to object within the 2-week review period will be taken as approval
          5. Same deal of at least 1 month in template 'ci-build' release before being pushed into 'official' unless FMG or other governance body says to speed up timeline (e.g. due to ballot)
        3. product family = management group
          1. Examples: Changes related to FMG QA rules that aren't shared across product families
          2. Same as previous, but just one management group.
        4. HL7 accelerator = outside this process - they can do what they like so long as they don't bypass rules/formatting in the base template
        5. community can also be tied to edge cases
          1. Examples: Corrections related to inter-version translation that impact implementations tied to a specific ballot release (that we choose to or are funded to support
          2. If few/only one implementer will ever care about the requirement, may consult only those directly affected
          3. If few/only one implementer will be impacted now, but more will be impacted later, then broader consultation is required
    4. Decide whether solution will be toggleable (IG authors can decide whether the feature exists in their IG or not) and/or trialed (feature is released into a branch IG authors must specifically adopt to use for a period of time)
      1. Hard to toggle changes to publisher.  Toggling template changes can be easy or hard depending on nature of change.
        1. Examples of hard-to-toggle changes: Changing the layout of the differential view to use a completely different template layout
      2. Toggleable = "is possible" and "is this something that might reasonably be different from IG to IG"
        1. Something might be toggleable at the 'base' level, but be locked for HL7 or a particular product family
        2. Toggling adds complexity to testing and ongoing maintenance
          1. Could theoretically disable toggling support if we find 'everyone' is using the feature
        3. Need to establish what the default state is for IGs that don't set a switch.
      3. If not togglable, then more effort may be needed to form consensus.
    5. When there is not clear consensus about a change and togglable is not an option
      1. Final proposal based on all feedback to date will be put out to the ig-publisher Zulip stream for an up or down vote
      2. Notification of the vote will be sent to the Committers/Announce stream, as well as emails sent to the Co-chairs, management group and international council list servers or contact emails
        1. Announcement will indicate that discussion is expected to happen on the ig-publisher Zulip stream and provide a link to the relevant stream.
      3. Voting will be open to anyone who cares to participate and signs up for the ig-publisher stream in that period of time
      4. Minimum quorum is at least 5 participants
      5. Vote period will be 2 weeks
      6. 50% +1 majority of votes cast will determine outcome, though if the vote is close, the project group will strive to see if accommodations can be made that will produce a more 'consensus' position.
      7. If management groups object to a change, the change will be put on hold, pending resolution of management group objections
      8. If there are concerns about process or severe negative impact on a particular stakeholder group, concerns can be escalated to the TSC
    6. Prioritize & size/estimate implementation of the solution
      1. If size/cost is bigger than can be done on a volunteer basis, tag as "resources-needed"
  4. Solution implementation
    1. assign/take responsibility
    2. Implement proposed solution
    3. Test proposed solution
      1. Must test multiple IGs
      2. Must test multiple product family versions (based on which families are impacted by the change)
    4. Ensure documentation is updated
      1. sample-ig or other ig that demonstrates the change
      2. documentation on ig-guidance for users of how to interpret/understand the rendering (if change affects what a user sees)
      3. documentation on ig-guidance and/or Confluence for authors of how to use the new feature (if the feature is configurable)
      4. documentation on ig-guidance and/or Confluence for authors of how to override the feature (if feature is designed to be overridden in downstream igs)
      5. release documentation that explains changes, including any dependencies between template version and publisher version
  5. Project group sign-off
    1. This group reviewed and ensures the change is implemented as agreed (or accepts deviations), reviews documentation, and agrees change is ready to move to #current
  6. Solution deployment & issue resolution
    1. Changes are merged into master branch of IG-publisher and/or the affected IG template(s)
    2. Changes to the templates will be effective immediately for IGs that use the #current release
    3. Changes to the publisher will affect all IGs when the next release of the publisher is issued
    4. Release of the IGPublisher and changes to the #current release of the IG templates can occur at any time, though in the 3 weeks immediately preceding a ballot cycle, only content deemed critical to ballot or time-critical publications (typically just bug fixes) will be permitted.
      1. Critical = content that will prevent either balloters or implementers from safely and accurately interpreting and/or implementing the specification or that prevent publication of content.  E.g. snapshot generation is incorrect, elements are inappropriately suppressed, table of contents incomplete, some changes aren't highlighted as changes (when other changes are), etc. would all be 'critical'.  On the other hand, table rendering being 'ugly' but readable, example narratives not appearing, spurious warnings during the generation or QA process would be non-critical.
      2. Where fixing a 'critical' issue might require a delay to ballot opening or publication, management groups and/or TSC will make the determination as to whether the issue is sufficiently serious to justify a delay
    5. GitHub issue is marked as resolved
  7. Solution is pushed into an 'official' template release
    1. This will happen on a regular schedule (tri-annually post ballot opening, prior to WGM).  Urgent changes may be released in shorter time-frames and major changes that require more testing might be released more slowly.
    2. Confirmation of including a feature as well as release numbering in a release will be made by this group,
  • No labels


  1. Recommend standardizing all processes to occur within JIRA where possible, vs. github

    1. We recognize that some users will raise issues in Jira (in part because they may not realize that something is a tooling issue, or because they don't know what 'layer' (or layers) of the tooling addressing the issue will impact.  However, for actually managing the tooling changes, Git is most appropriate as it integrates directly with commits and is how developers are used to working.

      1. The v2MG agrees with the suggestion that the review and initial proposal phases should be in Jira rather than Github. The detailed solution design and implementation can definitely be in Github, but like other comments or enhancements against an HL7 product, if seems like the dispositioning should be consistently in Jira.

        1. Revamped to indicate that changes falling under the scope of this process will be managed in Jira.  (Other stuff like tooling bugs will live in Git.)

  2. 3b should be a "sizing" activity to clarify which scope of the community the proposed change delivers value to, not really about which community you have consensus with, I don't think

    1. It's sort of a mixture.  If something delivers value to a community, but there isn't consensus across that community that it's wanted, we may not be able to enable the feature across the community.

  3. 1.b Issues may be raised via private email, GitHub issue, on Zulip and/or in Jira

    While initial discussion can be in any of these forums, the v2MG feels like ultimately there should be a Jira ticket created for tracking purposes. This aligns with the comment above that review and initial disposition should happen in Jira.

    1. Agreed to a Jira ticket process for enhancements that fall under HL7 purview.  However, managing bugs, etc. that are outside of HL7 responsibility will be handled in Git.  The differentiation reflects "who decides".

  4. 2. Issue Review

    The v2MG isn't clear on what the outcome of the "review" phase would be. Is this step necessary or is it really just a part of the Solution Design and Planning phase?

    1. Agree.  Folded into 3.

  5. The v2MG isn't clear on the functional distinction between deployment and official release. During the 1 month post-deployment phase, is the 'current' release the FHIR IG current build site (or the equivalent for a CDA or v2 change)? If so, what does the "official" release do that is different? How will the deployment be timed? Could something be deployed in the weeks just before ballot opening and potentially impact a teams ability to complete their IG for balloting purposes?

    1. Revised section 4 to hopefully make things clearer.  Short answer is - yes.  Changes can be released to the publisher and #current templates just a few days before ballot opening if they're deemed critical.  More minor changes will be deferred in the period directly leading up to ballot.  For templates, there's also the option to rely only on 'official' rather than 'current' releases of templates which provides more stability (unless the FMG decides that the 'official' release needs an urgent fix).

  6. The v2MG is uncertain about the edge case described in 3.b.ii. How would it be determined that a change would only interest or effect one or a few projects? Is there a downside to making all changes known to the larger community?

  7. The v2MG would like to see additional clarification around the voting process for controversial changes. Would it be possible to vote in Jira rather than on Zulip?

    Who would be eligible to vote? Anyone on Zulip? Or only HL7 members who may vote as part of a regular ballot cycle? What safeguards would there be about stuff the ballot box by people not regularly involved in discussions but recruited by a particular side (admittedly, we may be a little paranoid about this one)?

    1. Jira voting is not an option.  (The 'vote' capability in Jira is global - either all projects have it or none, and we've turned it off everywhere to avoid confusion with formal HL7 voting processes.)  Have added clarifications about expectations as well as escalating concerns about process violations.

  8. 5. Work group sign-off

    The v2MG would appreciate clarification on this. Does "Work group" refer to the FHIR-I WG or all work groups signing off on the change? We assume (and are OK with) the former, but would like clarification.

    1. Have corrected to "Project group"

  9. The v2MG wonders where FHIR Shorthand fits into this process. We assume that the FSH team may need to adapt to IGpublisher or template changes too. How will that be handled?

    1. FSH is an alternate "input" and thus would be subject to this process, though as long as their content is an 'optional' input, it shouldn't escalate to the controversial management phase.  Also, this impact is already accommodated, so we don't anticipate further discussion on this aspect.  FSH should not involve any template changes unless we start to have the ability to render things as FSH or maybe some example-generation machinery, in which case it would be a template/publisher change like any other.

      Decisions about what syntaxes are "official" or are allowed for exchange is managed through normal ITS and FHIR-I workgroup process and ballot.  This process only involves changes to IG input or rendering.

  10. I entered a number of comments directly on the text. Please review and address - thanks. Lloyd McKenzie 

    1. All have been addressed.  Please mark those you consider acceptable as 'resolved', or add additional comments/concerns.

  11. Comments from TSC members via their e-vote on the document:

    Comment from Jean Duteau : Although, at first glance, this appears like a reasonable process, I'd like some examples of what the group thinks are enhancements and what are critical fixes. I also would like to see a much clearer delineation of what is done in the IG Publisher tool versus what is done in the templates. From my work in IG guides, that line between tool and template appears to be very blurry. It may not be which is why I need to see that defined so that we can judge the impact of a change request.

    Comment from Ulrike Merrick : I have not used the FHIR IG publisher, so have no idea what the difference is between template changes and publisher changes, but agree if there is a difference, then that needs to be more clear. I have added some comments on the page directly, too.

    Comment from David Pyke : Will TOOLS have more than just FHIR Tooling in it? "3 management groups and maybe TSC" should be 4 mgt groups and when TSC should be outlined. Right now, the IG Publisher mostly works on snapshots with few (one?) actual release. Will this start moving the publisher and templates to more actual releases?

    Document was discussed on the 2021-11-01 TSC Agenda/Minutes where it was also noted that TSC would be identifying some members who will be participating more directly in the development of this process.

  12. Addressed the first part of Jean Duteau's comments with new sub-bullets under 6.d.  The second part of Jean's comments are addressed in the comment response to Ulrike Merrick's comment.  In short, there's no boundary that anyone other than a tool-smith will understand, and in general, no-one should need to.  David Pyke's comments were addressed inline.

  13. Comments about Accelerators (3.c.ii.3) (accelerator = outside this process - they can do what they like so long as they don't bypass rules/formatting in the base template) seems like it doesn't below in with Product Family.  Can comments about Accelerators be moved into the next level which discussing "levels of community".  Accelerators may actually focus on multiple Product Families - they are more organized around certain stakeholder needs, or a specific set of use cases.

  14. 1.b. change wording to ... submitted as Jira (preferred) or Github tickets.

    1.c. "this FHIR Infrastructure project" - Should this say "the FHIR Infrastructure IG-TOOLS project" or maybe this should be after 1.d.?  Will a link be added to the project?

    3.b.ii. WIll this need to change since the CTO role is going away being replaced by two new roles?

    3.c.ii.2. current release - is this the ci build?

    1. 1.b done

      1.c - this is referring to the HL7 project, not a 'Jira' project.  This page is already a child of the project page, but we've updated it to point to its parent

      3.b.ii - Once the CTO role is replaced, we will seek advice as to what to change this to

      3.c.ii.2 - Clarified

  15. 4.a. 

    1. assign/take responsibility  Can we clarify that the person who takes responsibility needs to publish their expected completion date for the work. Further, if things change, and there is a new expected completion date, this needs to be noted, and items that are blocked or at risk for not completed according to the projected schedule need to be identified as such. There needs to be a governance/escalation path for items that are not being completed on schedule.
    1. Given that all tooling enhancements are performed by volunteers on an "as time permits" basis, commitments will be rare and failing to meet commitments will not be uncommon.  As well, some tooling changes will have dependencies that aren't unknown.  This project will try to be responsive to the community and when asked for an estimate of when changes will be made, we'll do our best.  However, the only practical effect of 'escalation' would be for the TSC to seek out more volunteers to do the work.

  16. Please develop a basic gant chart to indicate publisher + template release cycles – key piece to highlight is when to expect lots of changes (unstable!).

  17. Took another pass - adding in-line comments.