Managing Specification Feedback

This page supplements the base Specification Feedback page by providing guidance to HL7 participants who have the authority to manage feedback issues.  That includes all users who have been added to the "hl7-trusted-users" group, which includes co-chairs, facilitators and other individuals who are helping to develop and maintain HL7 standards and who have been authorized by their work group to have management privileges.

Before reading this page, please read through the Specification Feedback page as this page presumes familiarity with the basic state machine and behavior of specification feedback issues.  The focus here will be on the additional capabilities available to managers.

Editing issues

Edits should be done with caution:

• It's ok to edit descriptions and summaries, but only to correct spelling or grammar issues that might affect readability or searchability, never to change the context of what's requested unless there's a record of a comment from the original submitter requesting the change.  Additional clarifications should be captured as comments, not edits.
• Changes to categorization (relevant artifacts, pages, links sections) should also be made with caution, especially if the item is tied to a ballot submission.  The scope of the comment can't be increased or decreased
• It's fine to add additional "Request in-person" individuals if you're confident they wouldn't mind being added (though it's good to add a comment to explain why), but no one should ever be removed without their request
• If you're going to change the work group assigned, you should provide a comment explaining why

There are four mechanisms for modifying the content of an issues:

Edit workflow option

As described on the base Specification Feedback page, this is the only edit option available to regular users.  It is only available to the reporter, allows editing of a limited number of fields and can only be used if the issue has not been linked to another issue (e.g. ballot vote, duplicate, etc.).  If you're a manager or administrator, you won't have access to this option - because you can use one of the other options listed below that are more useful/powerful.

Edit menu item

Just click on the Edit button on the left-hand side right under the issue summary.  This will let you edit all of the "editable" fields for the issue.  The only fields you can't change this way are:

• Assign - this field can only be changed by using the Assign button or the Assign to me link
  • Assignee
• Non-changeable - these fields are either fixed or calculated and cannot be edited
  
  • Reporter
  • Outstanding Negatives
• Move only - these fields can only be changed by 'Moving' the issue - see below
  • Project
  • Issue Type
• Workflow only - these fields can only be changed by pressing one of the workflow buttons.  The workflows and associated fields are listed below:
  
  • Duplicate
    • Duplicate Issue
  • Change Workgroup
    • Work Group
  • "Propose Disposition" (or one of the actual disposition transactions)
    • Applied for Version
    • Change Category
    • Change Impact
    • Pre-applied
    • Resolution
    • Resolution Description
    • Resolution Vote
    • Vote Date

Editing from the 'view' screen

In addition to using the 'edit' button, you can also just click on one of the editable fields displayed in the 'view' screen and change the values.  However, because the view screen only displays fields that have values, you'll have to use the Edit button if you want to set a value for a field that doesn't yet have one.

Workflow Transitions

As mentioned above, there are certain fields that are only changeable by invoking one of the workflow options.  Exactly which fields will be available will depend on which workflow is invoked.

Moving issues

Sometimes when an issue is created, it'll be captured under the wrong feedback project (e.g. CDA issue captured under the FHIR project) or the issue type will be incorrect (e.g. Question that's really a Change Proposal).  Fixing these requires "moving" the issue rather than a simple update.  That's because the fields, statuses, resolutions, etc. associated with the issue can theoretically change when changing the Project or the Issue Type.  Jira will allow you to move an issue to or from any other project in Jira, but you'll run into a disconnect of fields unless you limit moves to only be with other Specification Feedback projects.  (And might run into issues even then if the specification feedback projects have diverged from the standard template.)

Moving is only possible when items aren't yet resolved (i.e. status is Submitted, Triaged or Waiting for Input.  Particular caution is needed if moving an item that is tied to a ballot vote.  In general, don't move items that are ballot-related, especially if they're weighted as normative.  Instead resolve the existing issue as appropriate for its current categorization and create a new related issue, if appropriate.

To move an issue:

1. click on More, Move
   
2. Specify the new Project and/or Issue Type, then press Next
3. You'll see a list of fields that have been removed and added - these should all be Message fields, which you don't need to worry about.  Press Move to confirm

IMPORTANT: Never move issues except between issue types within a single project or across Specification Feedback projects.  I.e. moving between FHIR, CDA, V2 and Other is ok, though items that have been balloted should never be moved except within the same project.  NEVER move a Specification Feedback to a non-specification feedback tracker.  If the result of a spec feedback tracker item is the need to create a UTG request or new project or some other action, then create a brand new issue and link that issue to the existing feedback issue. Moving issues will likely break the workflow processes associated with the new project and will also mean that the issue will no longer show up in queries of the Spec Feedback project. (And if the issue was associated with ballots, it'll no longer show up in ballot counts, etc.)

Cloning issues

Sometimes you may want make multiple copies of an issue.  For example, the same problem might exist in resources associated with multiple work groups.  Rather than re-typing the information for each issue, you can create a single issue and 'clone' it, then adjust each to reflect the appropriate work group and issues.

To clone an issue:

1. click on More, Clone
2. Adjust the summary (don't create an issue with the word 'CLONE' in the summary) and click Create

Workflows

One of the major functions of managers is to progress the issue through the issue workflow.  This will mean choosing actions from the workflow menu.  The set of options available to managers will be much broader than for regular users.  As a result, it'll be important to look for options under the Workflow menu button as well as the two options immediately to the left of it.

Triaging issues

The Submitted state is a temporary state that allows review of the issue content prior to work groups needing to concern themselves with the issue.  Typically, work groups will ignore content in the Submitted state (in part because it's quite likely that no work group has even been assigned to the issue).  Instead, specifically designated managers (who will often also have administrator privileges) will review new proposals and ensure that they are complete and clear and ready for work groups to deal with.  Specifically, that means checking the following:

1. Does the issue contain content that violates HL7's Acceptable Use Policy (e.g. vulgarity, advertising, rudeness, etc.)?  If so, the webmaster should be informed so that the user can be reprimanded/banned and the issue Deleted.  (This requires administrative privileges.)
2. Check and make sure that issue has been submitted under the appropriate Project and with the Issue Type.  E.g. If it's a change that falls within the category of a technical correction but it hasn't been categorized as one.  If not, then Move the issue to the appropriate Project and Issue Type.
3. Is the issue sufficiently clear that a work group could reasonably make a decision about the issue?  If not, the issue should be "Assigned" to the reporter, with a comment providing guidance on what additional clarity/detail is needed to make the issue actionable.  (Assigning the issue will automatically change the status to Waiting for Input.)  The issue can also be 'Assigned' if information is needed from some other party prior to making a triage decision.
4. Is the issue a duplicate of something that's already been submitted?  If so, mark it as a duplicate (see below)
5. If the issue is a technical correction, evaluate whether the requested change is obviously needed and, if so, auto-approve it.  This will transition it right to "Resolved - Change required".
6. Otherwise, click the Triage button and ensure that other elements are appropriate filled in (artifacts, pages, release, etc. and that the issue has been tied to the appropriate Work Group.  When you press "ok", the issue status will progress to "Triaged".  (Note that Work Group is mandatory to progress to Triaged.)

Waiting for Input

Issues can be assigned to others for a variety of reasons.  They might be assigned to the reporter to provide more clarification.  They might be assigned to a domain expert for investigation or additional advice.  They might be assigned to an implementer to report back on connectathon or other experience, etc.  Any time additional information is required before a work group feels comfortable resolving an issue, the issue can be assigned to someone whose responsibility is to provide that additional information.

Note that Assignment is only possible to users with an HL7 Jira account.  This should be most co-chairs and faclitators, as well as anyone who has ever submitted a feedback issue, including those who have submitted ballots - so a pretty wide pool of people.  If you want to assign to someone who doesn't have a Jira account, you'll need to prompt them to create an account first.

Assignment is only possible to a specific person, not a group or organization.  The assigned person may involve others in gathering the information needed to provide the answer, but only the specific assignee will receive the weekly emails reminding them to provide the requested information.

Work groups are still responsible for the timely resolution of tracker items even if they're currently "waiting for input".  If an issue is stalled with the current assignee and the assignee is unresponsive to reminders/queries for a period of weeks or months, it may be necessary to find an alternate assignee or find some other mechanism to move the issue forward.

Once input has been provided, the issue will automatically return to either "Submitted" (if no Work Group is provided) or "Triaged" (if Work Group does exist).

Duplicate

Users should ideally search through existing issues before raising a new issue, but not everyone does (and even if they do, not everyone will find relevant duplicates).  Marking an issue as a duplicate says "All discussion - and eventual resolution - of this issue will be conducted on the referenced duplicate issue".  This allows work groups to be more efficient and lessens the chances of coming up with conflicting resolutions to what is essentially the same issue.

It's only possible to mark an issue as being a duplicate with an issue that's still "open" - i.e. Submitted, Triaged or Waiting for Input.  If an issue duplicates an issue that's already resolved, it can be voted as "Considered - No change required" with a reference to the resolved issue.

To be considered a duplicate, the issue must be the same as the referenced duplicate and can't have additional information that might lead the work group to make a different decision.  If two issues are closely related, but not strictly duplicates, you can link them using the Related Issues field.

If two issues are true duplicates, but each have relevant comments, add a comment to the surviving "target" issue from the comments of the 'duplicate' issue, providing attribution as relevant.  That way someone reading the surviving issue can see all of the key points without needing to navigate to any of the linked duplicates.

Be particularly cautious about marking issues as duplicates if they have associated ballot comments because doing so will transfer the ballot comments to the "surviving" issue.  As well, the process will enforce that the issue type, specification, artifacts and pages associated with the surviving issue are a match for the votes to be moved and, if not, will prevent the duplicate assertion.

A vote isn't required to mark an issue as a duplicate.  However, having a vote is a good practice for normative issues unless the duplication is super-obvious (i.e. the issue looks to be a copy & paste of the original).

Resolving Triaged Issues

Once issues have been triaged, it then falls on the responsible work group to resolve the issue - answer the question; approve or reject the change proposal, etc.  In some cases, work groups will need to vote to approve the disposition.  In other cases, the issue can be resolved without a vote.  The resolutions permitted and whether a vote is required are dependent on the type of issue raised.  The following table provides a high-level summary of the possible workflow steps that are possible for a Triaged issue.  The columns represent the different ssue Types allowed for Specification Feedback items.  The rows list what Resolutions are possible.  Cells show what workflow transitions (italicized text) can be used to achive that resolution and what fields can be (or if bold, must be) set as part of the transition.  Empty cells indicate that the Resolution is not applicable for that Issue Type.

Common questions

Q. What if I have a comment or question but want to make a change based on it? A. Move the issue to the appropriate type (if not a ballot item) or create a new related issue to handle the desired change.  By definition, comments and questions can't result in changes.

Q. Why can't I resolve a change request or technical correction as "Considered - No action required" or "Considered - Question answered"?  A. If someone has requested a change, then it must be resolved accordingly.  If they haven't requested a change, the issue should be Moved to the appropriate Issue Type.

Q. Why can't I have a "Persuasive with Modification" or "Not Persuasive with Modification" resolution on Technical Corrections?  A. For something to be considered a "Technical Correction" it must be an obvious fix.  If sufficient change is required that the proposed change cannot be made with only minor modifications, then the proposed change doesn't meet the expectations of being a "Technical Correction" and it should be Moved to "Change Request" and treated accordingly (e.g. resolution is voted on).

Q. Where's the "Not Related" resolution?  A. "Not Related" applies to a particular vote, not to a feedback item.  It's possible that the same feedback item might be voted on by multiple people - and possibly as part of multiple ballots.  The item might be "Not Related" for some ballots, but related for others.  Even if found "Not Related" from a ballot reconciliation perspective, the item might still be relevant and result in a change to the specification - either immediately or at some future point.

Q. Why aren't there votes except for Change Requests?  A. Comments and Questions do not result in any change to the specification and Technical Corrections can't result in substantive or controversial changes to a specification.  As well, none of them can be associated with negative votes.  Work groups who wish to vote on such items can do so and can record votes in their minutes or, if they choose, capture votes on the issue using the Propose Resolution transition.  However, they are not needed and we do not want to encourage work groups to incur this overhead when resolving issues.

Q. Why are there separate transitions for Pre-applied?  A. If an item has been marked as pre-applied and a change is approved, the work group must decide whether the approved change is the same as the pre-applied change.  The distinct transitions help to enforce the need to make this determination.  As well, if the change has been made "as pre-applied", the transition will automatically transition the status to "Applied" rather than just "Resolved - Change Required".

Guidance on Resolution Descriptions

• For a Question must be the answer to the question
• For Not Persuasive must be an explanation of why no change is being made
• For Persuasive with Modification, must be an explanation of what change will be made
• For Not Persuasive with Modification, must include an explanation of why the proposed change won't be made as well as what change will be made
• For a Comment, no description is required, but if desired a simple "Thanks" or "Ok" or something can be included
• For Persasive, no description is required, but if desired a more detailed description of what change will be made will be useful.  E.g. intended new wording when the submittted issue just said "clarify".

Additional Guidance

• Persuasive, Persuasive with Mod and Not Persuasive with Mod means that there's a commitment to modify the specification (either directly or through tooling) as part of the next release (or whatever release is indicated for the change).  If there is no intention to make a change because of this specific issue, then those resolutions can't be used.
• If you are not going to make a change because of the specific issue (e.g. because the issue is addressed/superceded by another non-duplicate issue), you might need to find the resolution Not Persuasive even if you agree with the intent of the balloter.  It's also possible to find an issue "Not Persuasive" and include in the resolution a reference to a new tracker intended to address the underlying issue.  (E.g. if the comment is tied to a ballot and thus transfer to a different work group/change of scope is not appropriate.)
• The mover and seconder in a vote must include both first name and last name.  The whole vote must be captured in the format specified - mover and seconder separated by a "/", the seconder followed by a ":" and the for, against and abstain vote numbers separated by "-"
• When recording a vote, make sure the vote actually passes - i.e. affirmatives > negatives.  Also, you should have more than one affirmative vote.
• AppliedForVersion is assumed to be the "next release" unless otherwise specified
• If you need a version, specification, artifact or page that's not in the drop-downs, talk to one of the administrators for the Specification Feedback project for your product family.  (And if you don't know who that is, reach out to webmaster@hl7.org.
• If you're updating the descriptive information for an issue during a call and haven't decided what the resolution should be yet, consider using the Propose Disposition action - it'll let you fill everything in, including the vote once a decision is made.  However, don't forget to click the actual disposition button once you're done.  The resolution isn't official until the status is changed - and that doesn't happen until you hit the appropriate workflow button.
• Pre-applying changes (making a change to the specification source prior to approval) may be useful in a couple of situations:
  • When approval of the change seems pretty much a "slam dunk" and you're trying to meet a deadline
  • When it might be hard for the work group to understand the impact of a change without seeing it
• In either case, make sure it's easy to roll back the change if it isn't approved (or isn't approved as pre-applied).  Also, be sure to set the Pre-applied flag so that everyone remembers that it may be necessary to roll back the change (or that no further change will be necessary) once the final resolution decision is made.
• It is permissible to resolve issues that are raised during during ballots (whether voted on or not) prior to ballot closure.

Comments

Comments are an important part of issue resolution.  They provide an opportunity for people who have opinions or insight on a proposal to share that information with the group that will make the decision.  They also provide a mechanism to provide guidance about what information is needed when Waiting for Input.  Finally, they allow recording interim discussion or decisions when a work group reviews an item but don't reach a decision.

Comments against an issue should always be reviewed before making a final decision on the disposition of an issue.

Regular users are restricted to only recording comments against "open" issues.  Once an issue has been resolved, they can't comment anymore.  If they want to raise a point of discussion, this needs to be done as a new issue (or on a discussion forum).  That's because work groups don't necessarily look at comments made against resolved issues and the feedback might be ignored.

On the other hand, managers can comment on issues once they've closed.  This allows capturing additional thoughts during the "Apply" phase, thoughts on a deferred issue to be considered when it comes back, etc.  However, be cautious when taking advantage of this capability and be aware that work groups might well not look at whatever comments have been recorded.

Post-resolution transitions

Re-opening an issue

After a decision has been made on how to resolve an issue, sometimes there's a need to change that decision.  Perhaps the workgroup realizes that they misinterpreted the issue or there's a problem applying the resolution as agreed.  For "duplicate" issues, you can mark them Non-Duplicate.  (Note that this will not return votes migrated to the duplicate issue, which is why marking voted issues as duplicates needs to be done with considerable caution.)

For other statuses, you can "Re-open".  Re-opening an item is only possible if there aren't withdrawn items for "locked" ballots.  I.e. If someone has withdrawn a negative on the basis of a resolution and the final vote count has been taken, then the resolution must stand as written.  Re-opening will require a comment explaining why the item is being re-opened. 

Once re-open performed, the original work group disposition information will be copied into a comment and wiped from the disposition fields.  Any ballot votes withdrawn based on the previous resolution will be reinstated and ballot totals will be updated accordingly.

Re-opening issues generally requires a vote.

In short - don't re-open ballot-related issues without good cause.

Applying changes

Once a resolution of Resolved - Change Required has been approved, the change can be applied to the specification's source - whether managed in Git or in some other environment.  Once the change has been applied, that should be reflected by clicking the Change Applied button.  If the change is captured using source control, the Git commit id should be included in the "change applied" comment - and the Jira issue id should be included in the commit message.  If there are any deviations as part of the change application, those should be noted as well.

Sometimes when you get to apply a change, you may find it's already been done (as part of some other change request, or perhaps as incidental clean-up of typos and grammar as someone was fixing other things).  In that case, mark the item as "applied" and just note that the change was already made by someone else.  The same thing holds if there's a request for a correction to text or an artifact that no longer exists as a result of another change.

In other cases, the desired change may still be possible to apply, but might not make sense based on other changes that have occurred.  In that case, the issue will need to be re-opened and re-voted.

If something has been marked as "applied" in error, it can be transitioned back to Resolved - Change Required by pushing the Not Applied button.

Publishing changes

Marking applied changes as "published" can only be done by an administrator.  That step is only done when a new release of the artifact is officially published.  If an applied changed gets missed being marked as published by accident, simply let an administrator know.

If something has been marked as "published" in error, it can be trasitioned back to Applied by pushing the Not Published button.  This can be performed by managers, not just administrators.

Bulk changes

Managers will often need to make changes to a set of issues at the same time - marking them as scheduled for a particular meeting, transitioning a bunch of typos to auto-approved, marking issues for block vote - or applying the results of a block vote.  All of these objectives can be accomplished using the "bulk change" mechanism described in the general Specification Feedback documentation.  However, in addition to the limited transitions open to regular users, managers can perform all of the transitions they have access to - such as Traige or Change Applied.  In addition, managers have access to the Edit function.  So long as all the changes to be made to a particular group of issues are the same, it's possible to change up to 1000 simultaneously - though only issues that pass validation with the proposed changes will actually be updated.

A few things to keep in mind when making bulk edits:

• DO NOT use bulk edit with any of the following fields: 
  • Raised in Version, Related Artifact(s), Related Page(s), Specification
    
    • Enabling any one of these fields automatically enables all of them - and any field that's enabled will wipe the element if no new value is declared for it.  A defect has been reported with the underlying plugin, but they've indicated they don't expect to fix this any time soon.
  • Development, Epic Link, Rank, Sprint, issueFunction
    
    • These fields aren't used by the Specification Feedback project, but Jira doesn't provide a mechanism to hide/suppress them from the Bulk Edit view.  Changing these fields could cause unexpected side effects
  • Outstanding Negatives
    • This is a calculated field and should never be manually edited.  (If you feel the value in it is incorrect for a given issue, please contact an administrator who can verify the issue, figure out what happened and correct it.)
• You get to choose what fields you want to be included in an edit.  If you enable a field, as part of the edit, the value will be applied to all issues selected in the bulk edit.  If you don't specify a value for the field, then the content of that field will be wiped for all issues.  (So be careful!)
• Use caution when editing fields that can contain multiple values like Group or Schedule or that allow free text.  Whatever values you specify will replace everything in that existing field - there's no way to add or remove items from Group, Schedule, Request in Person or a text field like Resolution Description, you can only replace the full content.
• The 'Send email' option at the bottom won't actually do anything.  Emails on individual updates is disabled.  All issues affected by bulk edits will appear in the daily summary messages.
• Edits can bypass transition rules
• "Change Comment" doesn't actually change existing comments, it a new comment to all of the records

Move will only be enabled if all of the selected issues are moveable (i.e. all of the issues are Submitted, Triaged or Waiting-for-Input).

Defining dynamic elements

Some of the drop-downs in Jira are dynamic.