# Rules for Substantive Changes During FHIR Implementation Guide Ballots

## Overview
The governance of substantive changes during ballot cycles shall follow a sliding scale approach based on the FHIR Maturity Model (FMM) level of the Implementation Guide (IG). This framework establishes appropriate restrictions and sets clear expectations for content stability at each maturity level. Enhanced communication between specification authors, HL7, ballot participants, and specification consumers regarding these processes and their outcomes is essential.

## Maturity-Based Change Management Framework

### FMM 1-2: Early Development Stage
**Maturity Level:** Low
**Change Restrictions:** Minimal
**Stability Expectations:** None

Implementation Guides at this maturity level are in an exploratory development phase where rapid iteration is both expected and encouraged.

- **Ballot Purpose:** Serves as a checkpoint for gathering stakeholder feedback and establishing durable publication milestones
- **Content Stability:** No guarantees of stability for any content elements between ballot cycles
- **Change Philosophy:** Authors should prioritize innovation and responsiveness to feedback over maintaining backward compatibility

### FMM 3: Transitional Stage I
**Maturity Level:** Medium-Low
**Change Restrictions:** Moderate
**Stability Expectations:** Limited

Implementation Guides at this maturity level are suitable for limited production use and pilot implementations.

- **Ballot Purpose:** Represents a version that authors consider functionally complete and suitable for implementation, though not yet fully stable
- **Content Stability:** Substantive changes to existing content may occur between ballots but should be documented and justified
- **Change Philosophy:** Balance the need for improvement with growing implementation commitments

### FMM 4: Transitional Stage II
**Maturity Level:** Medium-High
**Change Restrictions:** Moderate
**Stability Expectations:** Limited

Implementation Guides at this maturity level are suitable for limited production use and pilot implementations.

- **Ballot Purpose:** Represents a version that authors consider functionally complete and suitable for implementation, though not yet fully stable
- **Content Stability:** Breaking changes may occur between ballots but should be documented and justified
- **Change Philosophy:** Balance the need for improvement with growing implementation commitments

### FMM 5: Production Stage
**Maturity Level:** High
**Change Restrictions:** Stringent
**Stability Expectations:** Maximum

Implementation Guides at this maturity level are in widespread production use where stability is critical for operational and regulatory compliance.

- **Ballot Purpose:** Represents a significant milestone with direct production and regulatory implications
- **Content Stability:** Changes must maintain backward compatibility unless exceptional circumstances warrant breaking changes, which require formal justification and transition planning
- **Change Philosophy:** Prioritize stability and predictability for existing implementations while carefully managing necessary evolution

---
Review
---

* [Current Process Overview](https://viewer.diagrams.net/?tags=%7B%7D&lightbox=1&highlight=0000ff&edit=_blank&layers=1&nav=1&title=HL7StandardsProcess.drawio&dark=auto#Uhttps%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1sTV7hHJhgDbro5vTELqUaRTYtBK8C2Wh%26export%3Ddownload)
* [Confluence: Ballot info](https://confluence.hl7.org/spaces/CDA/pages/256515910/CDA+Maturity+Model+Definitions+and+IG+Document+Template+Ranking+Approach)
* [Confluence: Lifecycle Expiration](https://confluence.hl7.org/spaces/~dvreeman/pages/389678779/Draft+STU+Expiration+Pathways)

----
Old content
----

Considerations for editorial work during ballots:

### The Problem

Personal experience:
* I voted affirmative on a ballot.
* The content of the guide changed in a very specific and significant way that I would *not* have approved.
* I am recorded as vote "yes" on the STU 1 version of the guide that is published.

### The Short Version?

Ballots involve two components:
* tickets - granular feedback about content of the specification
* a vote - overall approval or disapproval of the content of the ballot

Currently, an STU Ballot is allowed to:
* change any content between ballot and publication.

I believe the issues can mostly be boiled-down to the fact that balloting versions of specifications (even STU) *feels* like seeking an approval of the discrete content of the ballot, but that content is allowed to change considerably.

### The Short Version!

A sliding scale of restrictions (and expectations!) is appropriate. Additionally, we need to improve communication between authors, HL7, voters, and consumers of specifications about what these processes are and what they produce.

#### IG FMM 1-2

* Low: maturity, restrictions, and expectations about content.
* IGs in this category are in the "move fast and break things" stage.
* A ballot is a 'checkpoint' that can be used to both gather feedback and as a means for durable publication versions.
* There should be no expectations regarding stability of any specific content.

#### IG FMM 3-4

* Medium: maturity, restrictions, and expectations about content.
* IGs in this category are in a transitional stage (e.g., limited production use).
* A ballot is a version that the authors have some confidence in being useable and useful.
* Breaking changes should still be expected and tolerated.

#### IG FMM 5

* High: maturity, restrictions, and expectations about content.
* IGs in this category are in widespread production and stability is both expected and required.
* A ballot is a significant milestone that is expected to have production and/or regulatory impact.
* There are significant expectations about stability.

### Details

#### Terminology

1. "Resolving a ticket" is the activity of **voting** on a Jira ticket.
2. "During ballot" is the time that a ballot is open (i.e., from content freeze until the ballot closes)
3. "Reconciliation" is the time after a ballot closes until it is published.

#### Voting During Ballot

1. During an open ballot, it is inappropriate for a WG to vote on tickets.
2. Reason: while the ballot is open, the expectation is that a volume of tickets will be opened against the specification.
3. Reason: with the expectation that more than one ticket will be applicable, it is inappropriate for a WG to resolve a ticket without that information
4. Reason: Considering tickets targeting the same concept/text/etc. in isolation often causes conflicting resolutions and additional work.

#### Commiting During Ballot and Reconciliation (STU)

1. During an open ballot, approved changes can be made to the git repository.
2. If changes are substantive, they need to be **tracked** by the authors
3. Maturity level determines actions and restrictions
* Low: ? Providing the changelog during publication
* Med: ? Notifying ballot pool and providing option for feedback
* High: ? Notifying ballot pool and ensuring resolution / re-balloting?
4. Authors should be aware that they may need to roll-back changes made if they cannot be approved as part of the balloted publication
5. Voters need to be aware that content can be changed between approval and publication (with details on how/why)