FHIR gForge Tracker

The FHIR "Change Request" tracker is the formal mechanism for tracking all changes to the HL7 FHIR specification. It can also be used for tracking change requests for HL7 Int'l developed implementation guides. This wiki page provides guidance on using the tracker for both submitters as well as HL7 members responsible for managing tracker items. It also includes specific guidance for use of the tracker for ballot reconciliation.

If you have questions that aren't answered here, send an email to Lloyd McKenzie

Guidance for submitters

Who can submit?

Anyone!

There is no requirement to be a member of HL7 or an affiliate. All that's necessary is to sign up for a gForge account, which is free and open to everyone. Simply click on the "Register New Account" link in the top-right-hand corner and fill in the minimal registration information. A human will review your account request and confirm that you look like a human (generally within a few hours, but may take up to a business day). After that, you'll receive an automated email to confirm your email address (check your spam folder if you haven't seen anything after a couple of days). Once that's complete, you'll be able to post change requests as well as able to more easily browse, filter and explore existing change requests.

There is a slight difference in how we treat requests from members and non-members. HL7 members are permitted to vote in the ballots that approve FHIR as an official standard. Non-members can do this as well, but for most votes they must pay for the privilege. Comments submitted as part of a vote may be prioritized as such comments usually *must* be resolved before the specification can be published, while informal comments submitted outside of ballot aren't subject to such requirements. That said, HL7 takes the feedback of implementers very seriously and we'll do our best to deal with all comments received. (If you love process stuff, you can find the formal rules governing the ballot process and other processes here and here.

Why do we use gForge?

HL7 entered into an agreement with gForge many years ago and it is fairly widely used throughout the organization. We're aware that it has several issues and doesn't offer the features available with more modern tools. HL7's gForge is currently under review. However, for now, it's the tool we have.

Submission Rules and Guidelines

Requests should be concrete requests for change, not general questions or comments. (The latter can be raised on the FHIR Implementer Skype, Stack Overflow, the FHIR list server, the Disqus forum, etc. (Information on connecting to these sources can be found on the FHIR wiki.)
Requests should be based on the continuous integration release of FHIR. Changes will only be applied to prior releases if they represent catastrophic issues.
It should go without saying, but Please read through the relevant sections of the specification before requesting a change. Be sure you've looked at common extensions defined in profiles for the resource as well as the resource content itself. Also be familiar with the basics of how FHIR works
You can search against the continuous integration build using Google by adding "site:http://hl7-fhir.github.io/" to limit your search to the FHIR website.
Before submitting a request, please check for existing requests that deal with the same thing. (Filter by resource or page name is probably easiest, then scan the descriptions.)
If the topic has previously been discussed and resolved in a manner you don't find satisfactory, please reference the tracker number of the original request and provide some sort of new information to justify re-opening the specification
If you don't know how to fill out all of the tracker fields, that's ok. Your request will be triaged and properly categorized shortly after submission. Just fill in as much as you can.
1. If you're a brand new submitter, your name might not be in the "Actual Submitter" drop-down yet. Don't worry about it - you'll get added during triage.
If you're requesting that a new element be added to a resource, keep in mind the "80% rule" - we generally only add elements to the core specification if we expect 80% of all systems that use the resource throughout the world will use the element. Elements that are only common in a single country or a particular narrow discipline will likely be handled as extensions. Providing your arguments on why you feel the element fits within the 80% will increase the likelihood of it being added to core as opposed to being handled via an extension.

What happens after a change is submitted?

The first stage is triage - your request will be checked for completeness, assigned to the proper work group(s), etc. In some cases, it may be assigned a status of "Waiting for Input" if further clarification is required. Triage is usually done within 1-2 business days
- In some cases, requests might automatically get approved or rejected as part of the triage process based on pre-defined rules.
In the second stage, the work group will review the request and may either make further comments or make a final decision. The timeline for this phase may be anywhere from days to months.
If a change was agreed to, the change will then be made in the continuous integration build. Again, there may be a time lag before this occurs. If a request has urgency behind it, please indicate that in the initial posting.
The revised specification will go to ballot and the ballot respondents will provide feedback. As a result of that feedback, the agreed change may be altered or even reversed
A new official version of the FHIR specification will be published containing agreed changes

What else can I do with the tracker?

Search to see what change requests have been submitted for resources or pages you care about (including what changes have been agreed to, but not yet applied)
Add comments to existing tracker items (even if it's as simple as "+1")
Subscribe to particular tracker items of interest or (if you don't mind a busy inbox), subscribe to the whole tracker.
- Note: When we migrate ballot content or make other mass changes, subscribing to the whole tracker may net you a thousand or so emails over the period of a few hours - so mail management rules are recommended

Tracker Elements

This section describes the various elements of the tracker and give guidance on what they mean and how they should be used. Note that not all elements are available to be specified on submission - some can only be populated during triage and resolution.

Summary

This is the short description of the issue that is displayed in the "list" view of the tracker items. It should be relatively short (not more than 150 characters) but should cover enough details of the proposal that people scanning the list can get the gist of what the proposal is about. For ballot submissions, the summary will include the line item number from the ballot reconciliation spreadsheet.

Submitted By

This is the user under whose id the request was submitted. For "new" submitters who haven't been activated on the FHIR project, this may show up as "AAAA NonComitter" until triage is completed. For bulk uploads of ballot comments, this will show up as FHIR Bot. Because this element won't always be populated with the actual user (and because search on it requires exact name matching), the general advice is to look at Real Submitter instead.

Open Date, Close Date

The date when the tracker item was first submitted and the date on which its status was changed to a "resolved" status.

Priority

This defaults to Medium. Work Groups are encouraged to use this to triage comments for discussion. Statuses higher than Medium indicate items that should be resolved prior to the next release. Statuses below medium indicate items that can be deferred until after the next release. (The distinction between the two "high" levels and two "low" levels is left to the WG.

Assignee

This can be used to indicate who should apply the change associated with this tracker item or who is being waited on if the status is "Waiting for Input". (Note that tracker items can only be assigned to committers, so utility for the second use-case is limited.) Note that this element isn't frequently used.

Real Submitter

This is the name of the person responsible for the comment. In the case of ballot submissions, it represents the actual commenter, not the user id responsible for bulk upload, nor the person who submitted the ballot. If there are follow-up questions, this is who should be reached out to.

Ballot

This identifies the ballot the comment was submitted as part of. This element should not be edited unless manually entering in items from a ballot. Ballot submissions *must* come in through the HL7 ballot website. So even if you're raising a comment with the intention to associate it with a ballot, don't edit this field. It'll be automatically updated if you referenced the tracker item in your ballot submission spreadsheet.

Specification

This indicates whether the ballot comment applies to the FHIR core specification or one of the HL7-maintained implementation guides. The value here may be different than what's indicated in the ballot. Sometimes implementation guide comments are submitted as part of the FHIR core ballot and it's common for comments relevant to FHIR Core to be submitted as part of implementation guide ballots. This element can be changed by work groups and projects as necessary.

URL

This is the hyperlink to the page or to the specific area within the specification related to the comment. It should be filled in when possible.

Section Number

E.g. 1.2.3. You can use this plus the table of contents to find the specific area of the specification being discussed.

Resource(s)

This indicates the resource or resources associated with the change request. At least one resource or HTML page must be indicated on each change request. If a change applies to more than 5-6 resources, use the "(many)" option in HTML Page(s) instead.

HTML Page(s)

Indicates the primary web page(s) for the section impacted by the change request. Note that not every single page is indicated. Some just have a page for the general topic area. As well, there are pseudo-pages listed for items that apply to numerous resources, apply to profiles, etc.

Reviewing Work Group(s)

This is the work group responsible for reconciling the issue. In some cases, multiple work groups may be listed, in which case any of the work groups can resolve, though all should be notified of the intention to discuss (and any of them can force the item to be revisited once decided.)

Ballot-weight

This element is only populated for ballot submissions. It indicates the relative "strength" of the comment. Affirmative comments don't affect the ability of the specification to pass. Negative comments do. (Major ones represent significant objections, minor ones less so.)

In-Person

If specified, this indicates that the submitter would like to be present at the face-to-face session or conference call where the request is resolved. This request will be respected if possible, but is not binding on the work group.

Group

This element allows work groups to flag multiple items as being related to allow them to be discussed at the same time. Because gForge doesn't allow searching by non-drop-down elements, the values of this element are fixed (though additional values can be added - contact Lloyd McKenzie to add more if desired). The "ready for vote" group indicates that the item is ready for consideration as part of the work group's next block vote.

Schedule

This element allows work groups to identify when particular items should be discussed

Status

One of the key elements about a tracker item is the status. This section describes each of the statuses and any rules or guidelines accompanying their use.

Submitted

This is the initial status for all newly raised tracker items. It means that the various characteristics of the tracker item have not yet been checked and it may not be ready for work group resolution.

Triaged

This means that the tracker item is believed to be properly categorized and sufficiently complete for a work group to resolve it. (It's entirely possible that the initial assessment was wrong, so don't be afraid to re-categorize or re-assign if it seems appropriate.) This is the status representing items that are "ready for actioning" by the WG.

Waiting for Input

This means that the tracker item can't be further actioned until someone responds to questions identified as comments within the tracker. This may be the original submitter, a member of the WG that owns the item or someone else who has volunteered to do research or otherwise needs to be contacted. Note that work groups must actively manage items with at status of "Waiting for Input" to ensure that whoever is being waited on is regularly prompted and that, once that input is received, it is added to the tracker item and the status is changed back to Triaged.

Resolved - No Change

This indicates that the resolution captured for the item does not involve changing the specification. It may have been found non-persuasive or might have been a question or a comment that did not require action. This is a final state (though an item can in theory be re-activated)

Resolved - Change Required

This indicates that the resolution captured for the item requires some sort of change to the specification. Note that this doesn't mean that the change being made is the one that was originally asked for. This is not a terminal state - it will move on to Applied and then Published.

Duplicate

This indicates that the tracker item is essentially identical to one already submitted. The resolution to the referenced tracker item will be considered to apply to this item as well. If this status is specified, then there must be a single tracker item pointed to in the Duplicates list. That tracker's resolution will apply to this item. If the tracker item was submitted as part of a ballot and "In person" was requested, make sure a comment is added to the referenced tracker noting the in-person request. If there are additional nuances noted in this item not captured in the referenced item, append those as a comment too.

Deferred

This indicates that the tracker item will not be resolved as part of the current publication cycle but will instead be handled as part of a future release. From a balloting perspective, this will result in a reconciliation status of "Considered - for future consideration" or "Not persuasive", depending on the ballot strength of the comment submitted. All deferred items that are ballot items must be voted. Deferred items will be reset to Triaged after the publication of the next version of the specification

Resolution

This is the statement of what action is to be taken in response to the tracker item. If no action is to be taken, then this field provides a description of why no action is being taken. This must be present for the item to have a status of Resolved, Applied or Published.

Ballot resolution

This categorizes the nature of the reconciliation taken. This MUST be populated if Resolution Date is specified, though it may be populated earlier if there is a proposed disposition (e.g. prior to a block vote)

Persuasive: The work group agrees with the submitter and the specification will be changed as requested

Persuasive with Mod: The work group agrees with the submitter, but the specification will be changed in a manner that is not identical to the manner requested by the submitter

Not Persuasive: The work group disagrees with the submitter and will not make any change

Not Persuasive with Mod: The work group disagrees with the submitter but will make a change anyhow (e.g. to better clarify the spec)

Not Related: The work group has decided that the comment is out of scope for the ballot or for the specification overall

Considered for Future Use: The work group is deferring any action on this item until a future version of the specification (use with Status = Deferred)

Considered - No action required: No action was requested so none is being taken (use for category 'Comment') items

Considered - Question Answered: No change is being made to the specification but an answer has been provided to whatever question was asked

Resolution Date

The date on which the work group voted to approve the specified resolution. It MUST NOT be populated if the status is Submitted, Triaged, Waiting for Input or Duplicate. It MUST be populated for all other statuses if the tracker item is associated with a ballot, however it's good practice to populate regardless.

Retract/Withdraw

If specified, indicates the user has chosen to Retract (treat the comment as if it was never submitted) or withdraw (accept disposition, treat the line item as affirmative). It is only relevant for ballot-related items. It can be set directly by the submitter (if they have permission to update trackers). If not, a comment must be added by the voter indicating intention to retract or withdraw or a comment must be added by someone else referencing the conference call or meeting whose minutes capture the voter's decision or reference the email from the voter in which the decision was documented.

Change Type

This must be present for all tracker items that have a status of "Resolved - Change required", "Applied" or "Published"

Mover/Seconder: For-Against-Abstain

This must be specified (and may only be specified) for all items with a Resolution Date. It contains the name of the mover and seconder at the work group meeting that approved the disposition as well as the vote results. It MUST be specified in the format indicated (with the '/', ':' and '-' values included in the specified positions. Names should include both first and last name, though first name only is acceptable if the minutes associated with the resolution include full names (and the first names are unambiguous).

Pre-applied

If true, indicates that the requested change (or proposed resolution) has already been applied. This might be done to demonstrate that the change/resolution would look like or because the editor believes the likely outcome is for the change to be approved.

Target Release

This isn't generally used.

Details

Full details of the requested change, including rationale/justification

Follow-Ups

Additional comments made about the item over time

Files

This includes any supporting information, evidence, screen shots, etc.

Changes

This lists all changes made to the tracker item over time

Commits

This lists all SVN commits associated with the tracker. SVN commits associated with this element SHOULD include "[#" + tracker number + "]" as part of the commit to establish a link from the tracker item to the change made

Dependencies

Not used

Duplicates

This should only be populated if the status is "Duplicate", in which case it should only have one record listed - which points to the surviving change request. (If there are multiple duplicates, they should all have a single duplicate reference pointing to the surviving tracker item.)

Associations