Publisher-impacting Change Process

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,