FHIR Change requests

The gForge change request form is the means by which implementers and others can request changes to the FHIR specification. This page describes the rules around how change requests are to be used and maintained. The focus of these rules is allowing tracker items to be resolved as quickly and efficiently as possible, minimizing workgroup burden, while still ensuring due process and an opportunity to comment.

What goes in the change request tracker?

1. All changes to content that has been published in a DSTU must be documented as a change request. The change request log provides full traceability for how the specification has been changed and why. It also provides a single mechanism for interested parties to monitor and see what changes are proposed and to comment on those changes.

2. Changes to new resources, pages, etc. do not need a change request When content is in draft, it's expected to change regularly, so change requests are not required. The Resource proposal mechanism is sufficient to authorize work on a new resource or profile. That said, if a work group finds it convenient to use a tracker for some/all changes to an artifact that has solidified but not yet been approved at ballot, they're free to use it for that purpose

3. Items should only go in as a change request if a specific change is being requested. It should not be used to capture general points of discussion

Steps to propose a change request

1. Before you submit a change request, it may be worth discussing with the community. Simple typos, not so much, but the more substantial the change, the more important it is to discuss with the community - makes it more likely to be appropriate and acceptable. The best way is to use the implementer's chat to start a discussion in the community, or you can use the FHIR community forum.

2. If the community cannot provide a satisfying solution to your issue, feel free to open a tracker item. If a discussion on the issue has evolved on Zulip, please provide a link to the discussion in the tracker item.

3. You can use the syntax GF#12345 (with "12345" being your tracker item ID) in Zulip to reference the item, once it has been created. So other people involved in the discussion have a chance to add information to the request.

4. The tracker system will inform you when your request is up for discussion in the Working Group. Please do not contact the Working Group before the request has been triaged.

5. Please keep track of your request and make sure you receive the status update notifications, as the working group may need further information from you to process the request.

Triaging change requests

All submitted requests go through a triage process by one of the FHIR editors. The triage validates, populates and/or changes the request to do the following:

• Ensures the request is clear/coherent enough that the appropriate work group is likely to be able to properly evaluate it
• Ensures that the request is properly categorized as typo (clear, obvious spelling/grammar/wording error), correction (something that is clearly inconsistent/broken) or enhancement (everything else)
• Ensures that the metadata around which resource(s) and/or pages are impacted by the change is properly selected
• Confirms that the appropriate work group(s) or other bodies are associated with the change request:
  • Where the change is related to how the publication tooling functions, it will be assigned to publishing/tooling
  • Where a page or resources is "owned" by a particular work group, that work group will be listed
  • Where something affects the core operation of the FHIR specification, the FHIR Core Team will be listed
  • Additional work groups may also be listed if they are likely to have a special interest in the topic

The target is for requests to be triaged within a couple of business days of their submission

Re-assignment of requests

• Any member of a work group may add themselves as an interested party to a change request
• A work group may remove themselves from a change request if they feel it is inappropriately assigned provided that at least one other work group is identified as responsible for the proposal
• Work groups may be added or removed as based on the triage process
• Removal of a workgroup by someone other than a member of the workgroup should only be done with the permission of the work group (agreement of a co-chair or discussion on the list)
• Formal votes are not required to allow addition or removal of workgroups from a tracker item

Approval of requests

• Any request that is triaged as a Typo, the status will be changed to "approved" without requiring work group review
• Similarly, any request that is triaged as a correction to publishing/tooling will be marked as "approved" (provided the needed correction is clearly documented)
• All other changes require approval (by passing a motion) of at least one of the work groups listed as responsible. (The vote should be captured in the disposition)
  • Where a proposal has multiple interested work groups, those work groups must be notified of the intention to resolve an item at least one business day in advance of the discussion to allow interested participants to join the call/meeting or to include their thoughts as comments on the change request.
  • An email to the FHIR list server constitutes sufficient notice and is an encouraged best practice even when reviewing items not linked to any other work groups
  • If a member of a different work group requests that a tracker item be deferred to a joint call/meeting, that request should be respected if possible
  • In order to update change requests (other than adding comments), a gForge user needs tracker maintenance permission. If you need it and don't have it, ask Lloyd
  • when recording the approval, the minimum information to capture is : date, committee identity, motion mover/seconder, vote, and the wording of the motion

Revisiting requests

• No decision made on a change request is final until the completion of ballot reconciliation. (This is why the process is somewhat lax in terms of notification, joint resolution, etc.)
• Anyone may request that a decision be revisited by emailing the appropriate list server. All requests for revisitation should be honored by discussing the requests on a call or meeting, ideally with the requestor present

Applying changes

• Once a change has been approved, the changes may be applied by a work group member or by a member of the FHIR editorial team.
  • The editorial team must coordinate with the work group if they're going to make changes to ensure there's no collision (and to give the work groups a chance to increase familiarity with tools and processes)
• In some cases, changes may be applied prior to work group approval in order to provide a more concrete proposal for evaluation. However, a proposal must not be changed from "Triaged" until the change has been applied. (A pre-applied flag exists to easily find proposals where the proposed change has been pre-applied.)

Tracker Maintenance

The list of resources, pages, work groups and other drop-downs in the tracker are manually maintained. If you need something new added, ask Lloyd. (You can ask one of the other FHIR editors, but they'll probably still just route it to Lloyd :>)

If there's an additional feature that would make the trackers more useful, ask. We can add new fields and we're keeping a wish list of other desired features.