Co-chairs and project leads have responsibility for ensuring that the Jira Specification Feedback Project configuration information is kept up-to-date as the underlying specifications evolve.
|Table of Contents|
This page describes how to manage the process of configuring Jira Specification Feedback projects. It covers:
What files exist (and their content)
Rules and guidelines for maintaining them
Process for submitting changes
The specification feedback projects in JIRA are set up to allow certain elements to be customized. Specifically: Work Group, Specification, Change Raised in Version, Related Artifact(s), Related Page(s)
This customization allows the set of specifications to be adjusted as new specifications are introduced and older ones are retired. It also allows adjusting what portions of those specifications can be commented on as pages and artifacts are introduced, renamed, split, merged and deprecated.
Source of Configuration
Jira is configured such that the choice of the Specification changes what the available choices are for version, artifacts and pages. The 'source' that Jira uses to manage these different drop-downs is managed as XML files in the http://github.com/hl7/JIRA-Spec-Artifacts project.
NOTE: The structure of the Git project are set up to support artifacts from all product families. However, at present, only FHIR has a Specification Feedback project. Other product families should not use Jira for issue tracking until the appropriate tracker has been set up and approved for use by the Technical Steering Committee.
Guidance for maintaining Jira support files
There are several considerations to keep in mind when creating and maintaining Jira support files:
- Once a key is defined, it needs to remain unless we're absolutely certain that nothing in Jira references that key. That creates two sub-considerations
- Don't define an artifact or page in Jira until you're relatively certain you want it. If you're just playing around, consider holding off before adding it as something that Jira issues can be reported against
- The pull request verification process will not accept pull requests that remove a key. You can deprecate, but not remove. If you're certain that no Jira issue uses a given key and a pull request marking the element as 'deprecated' has already been applied, you can submit a request to have the element with that key fully removed (meaning it will no longer appear as an option for search).
- There's no requirement to have every single artifact and HTML page in your specification listed. It's possible to group all issues associated with a subset of artifacts or subset of pages under a single banner. When deciding whether or how to group things, keep in mind the following:
- The set of artifacts and the set of pages for a spec should be reasonable to scroll through in a drop-down list. Ideally less than 50 and if at all possible less than 100
- Think about how maturity levels will be established. Maturity is weighted by whether comments have been received against a particular artifact, so consider what makes sense to treat as a 'unit' from a maturity perspective.
- When naming things, try to align with the names in the spec, but include previous names or abbreviations if it's likely users will use those to search. (Prior names are particularly important if supporting submitting issues against past versions that still used the old names.)
Process for maintaining Jira support files
Implementation Guides that use the HL7 IG template
If using the HL7 IG template, once an initial specification file has been committed, the IG publication process it will generate a 'candidate' specification XML file if there are differences in the pages and/or artifacts defined in the current version of the implementation guide. . The initial version can be created from scratch (ignoring artifacts and pages other than 'generic' pages such as "(N/A)") or by copying from the Jira Spec file for an existing IG.
All other specifications
All other specifications will need to develop/maintain their specification file manually. It is the responsible of work groups planning to submit a specification for ballot to ensure that the specification file is in place in advance of creating a Notice of Intent to Ballot (NIB).
File to modify
New specifications will require modifying the SPECS-family.xml file to identify the new specification as well as defining a \[Family]-\[Code].xml file that represents the versions, pages and artifacts that are part of the specification. The \[Family]-\[Code].xml file should also be updated from time to time as pages and artifacts are added, renamed or deprecated.
The 'Code' should be the same code as appears at the end of the package-id for the implementation guide - e.g. for a package of hl7.fhir.uv.sdc, it would be 'sdc'. However, if the code in the package-id ever changes, the Jira code must remain the same. To allow the IG to link to the correct Jira file, add a parameter called 'jira-code' with a value of whatever the 'Code' is in Jira.
New files and updates to existing files can be performed by submitting a pull request against the https://github.com/HL7/JIRA-Spec-Artifacts project. The relevant files are all in the `xml` folder.
Most editors will not have permission to push directly to the JIRA-Spec-Artifacts project. Instead, they will need to make changes against a local fork of the HL7 project and initiate their pull requests from there. The process to do this is as follows:
- Ensure that you have a user account on Github
- Go to the https://github.com/HL7/JIRA-Spec-Artifacts website and click on 'Fork' in the top right-hand corner
- If it prompts asking where to fork, choose your personal account
- You will then end up at a github site of https://github.com/[your-git-id]/JIRA-Spec-Artifacts. You will have permission to make changes in your local fork
- Click the 'clone or download' button in Github and copy the URL
- In your Git client on your local machine indicate that you want to clone a Git repository and specify the copied URL as the URL of the repository. That process will create a local copy of the Git project on your local machine (so you can edit files locally rather than just on the web).
- In your Git client on your local machine, you'll also need to go into your Git settings for the new project
- Select 'remotes'
- Add a new 'remote' with a name of 'upstream' and a URL of https://github.com/HL7/JIRA-Spec-Artifacts
- This step is necessary so you'll be able to pull changes from the HL7 source of truth, not just from your personal web-based copy
- Ensure your local copy is up-to-date with the HL7 source of truth by performing a 'pull' and ensuring that the remote selected is 'upstream'
- Edit whatever files you need to in the 'xml' folder. (See below for guidance on what files to change.)
- Run the .buildLocal.bat file to ensure that there aren't any issues with your changes
- Warnings are ok if they don't pertain to your specifications.
- If they do pertain to your specifications and you're not sure if they're ok, ask on https://chat.fhir.org/#narrow/stream/184932-JIRA.2FConfluence
- Commit your changes to the repository on your local machine
- Ensure your local copy is up-to-date with the HL7 source of truth by performing a 'pull' and ensuring that the remote selected is 'upstream'
- If necessary, fix any conflicts, then re-test with .buildLocal.bat and commit again
- When everything is working correctly locally and committed, perform a push to your 'origin' location (not 'upstream'). This will place a changed version of the files on your personal git's web-based repository
- The "success" dialog for your 'push' should give you a link to make a pull request. If not, just go to your https://github.com/[your-git-id]/JIRA-Spec-Artifacts URL and you should see an option to create a pull request there
- Create a pull request, summarizing what you're changing
- Monitor your email for mail from Git either indicating a successful merge of your pull request or for comments asking for changes or asking questions
- If you run into any problems, ask on either https://chat.fhir.org/#narrow/stream/179293-committers.2Fgit-help or https://chat.fhir.org/#narrow/stream/184932-JIRA.2FConfluence
The Jira-Spec-Artifacts repository contains a number of folders. Most of the folders are for infrastructure and should not be changed by anyone other than an administrator. (Changes to the content of these folders might require changes to Jira configuration.) However, the contents of the XML folder is expected to be updated semi-regularly via pull requests by various HL7 participants. This section describes the files and their content. Most file properties are defined as XML attributes. Those properties that are XML elements are explicitly flagged.
This is a very small file that defines what product families exist. It should only be maintained by an administrator. In general, each family will correspond to a different Jira Specification Feedback project. The content of this file defines the 'prefix' for all specification definition files. E.g. FHIR-related specifications will start with "FHIR-", CDA-related specifications will start with "CDA-".
This is also a simple file. It defines what work groups are able to take on responsibility for a tracker item. This file will typically be maintained by HQ staff or an administrator. If you find you're missing a work group, contact the HL7 webmaster and they should be able to assist. The contents of the file are:
key: the unique identifier for the work group (what's actually stored on each issue). This will not generally be seen by users and should never change once established. Even if the work group is renamed, the key will remain the same
name: the descriptive name for the work group. This is what users will see - and can be freely changed if, for example, the work group changes their name. If renaming, it may be useful to include the old name in brackets if we expect users might still be searching by the old name.
webcode: the 'code' for the work group's home-page (i.e. the part of the URL following http://hl7.org/Special/committees/ when locating the work group's home page). This is used when helping to match ImplementationGuides to their work group using the ImplementationGuide.contact
deprecated: an optional boolean that can be set to 'true' for work groups that can no longer be assigned responsibility for tracker items. (E.g. because the work group has disbanded or been amalgamated with another. Don't do this if a work group has just been renamed.) Once deprecated, the work group will no longer be selectable when creating or editing work groups, but will still appear on historic issues and can be used when searching.
Anchor SPECS-[family].xml SPECS-[family].xml
These files list all of the specifications that exist for a given product family. There is one file per family. Pull requests to these files may be submitted by any co-chair, project lead or other individual involved in managing HL7 specifications. The file structure is as follows:
key: the unique identifier for the specification within the product family (what's actually stored on each issue). This will not generally be seen by users and should never change once established. Even if the specification is renamed, the key will remain the same.
name: the descriptive name for the specification. This is what users will see - and can be freely changed if, for example, the specification is renamed, perhaps due to expanded scope. It may be helpful to include the old name or abbreviations or other keywords to help users who are searching for the specification when submitting an issue.
deprecated: an optional boolean that can be set for specifications that are no longer actively maintained - and for which HL7 no longer wishes to receive feedback. This might be specifications that got merged into other specs, specifications that have been retired, etc. Once a specification is marked as deprecated, it will no longer be possible to choose that specification when submitting new issues or changing issues, but the specification will still appear on historic issues and can be used when searching.
This is the most important (and most complex) of the files. A separate file will exist for every specification (including deprecated specifications). The file includes information used to populate various Jira drop-downs associated with the specification as well as information that can be used to help identify the appropriate work group, validate URLs, default versions, etc. (Note - not all envisioned functionality is enabled yet.) The contents of this file are as follows:
url: The official URL for the specification. This is the version-independent URL that should resolve to the current official version of the specification. E.g. http://hl7.org/fhir/uv/sdc/
ciUrl: The continuous integration build URL for the specification. E.g. http://build.fhir.org/ig/HL7/sdc/
ballotUrl: The URL for the 'current' or most recent ballot (and which is eligible as a URL to report issues against). Issues can't be submitted against historical ballots, so only the 'current' ballot is needed. This can be omitted if there is currently no ballot where content should be submitted.
defaultWorkgroup: The work group that 'owns' the artifact and that should generally be responsible for resolving tracker items against the specification. This default can be overridden on a page-by-page and artifact-by-artifact basis. As well, during triage and resolution, other work groups can always be selected.
defaultVersion: The 'current' official version of the specification that should be presumed to be the version issues are being submitted against
version: XML element that indicates a version of the specification that feedback can be/may have been submitted against. Every specification must have at least one version. Additional versions can be added as needed. (Don't forget to update the 'default' version if appropriate.) Once created, versions can't be removed except by an exception process (see below)
code: The actual version code. This will be displayed to the user and should not ever change once established. E.g. 1.0.0
url: The URL where the specified version of the specification is available
deprecated: If this is set to true, indicates that feedback is no longer being accepted against the specified version. This should always be set for historic ballots, but may also be set for specifications where technical corrections will no longer be accepted.
artifactPageExtension: XML element with 'value' attribute that indicates additional pages that will be defined for each resource. This will be driven by the template used for publication. It's not currently used and it may be that it won't be needed. Ignore or accept the defaults for now.
artifact: XML element that indicates an artifact that feedback can be provided against (segments, templates, data types, profiles, value sets, capability statements, etc.). Once added, artifacts can't be removed except by an exception process (see below). They can however be flagged as deprecated.
key: The unique identifier for this artifact that will be stored in the issue. Users should not generally see this. Once established this should never change, even if the artifact id or name changes. (If two artifacts are merged into one, you have a choice of deprecating both of the original artifacts and creating a new one or treating one a deprecated and renaming the other.)
name: This is what users will see as the descriptive name of the artifact. It should generally be the same as the name of the artifact as it's published, but it might also contain acronyms, former names for the artifact or other information that will help users search for and select the appropriate artifact when submitting. This may be freely changed as artifacts are renamed, etc.
id: This is the formal artifact identifier. For FHIR-represented artifacts, this will be [ArtifactResourceType]/[artifact-id]. It is used to help partially auto-update the specification files as artifact names change
workgroup: This is the work group generally responsible for maintaining the artifact. It only needs to be specified if different from the work group generally responsible for the specification overall (i.e. where different artifacts and pages within the specification fall under the responsibility of different work groups).
deprecated: If set to true, this artifact will no longer be selectable when submitting new issues or editing previous issues. However, it will still appear on existing issues and be available for use when searching.
otherartifact: XML element with 'id' attribute that, if present, identifies the name of additional artifacts from the specification that are considered to be 'covered' by the root artifact. For example, if feedback about search parameters for a resource are expected to have their issues reported against the resource itself, grouping the search parameters here will allow Jira to automatically categorize submissions with a URL of the search criteria as being categorized under the resource instead.
page: XML element that indicates a non-artifact 'page' defined as part of the specification that feedback can be submitted about. These might include things like table of contents, home page, security guidelines, etc. This may correspond to an actual "web page" or to some sort of logical/notional grouping. It may also be the name of a category, including such things as "(N/A)". (Note that every feedback item must identify at least one artifact or page, so having an "(N/A)" page is generally recommended.)
key: The unique identifier for this page that will be stored in the issue. Users should not generally see this. Once established this should never change, even if the page name or url. (If multiple pages are merged into one, you have a choice of deprecating all of the original pages and creating a new one or treating one as a rename and deprecating the remainder.)
name: This is what users will see as the descriptive name of the page. It should generally be the same as the name of the page as it's published, but it might also contain acronyms, former names for the page or other information that will help users search for and select the appropriate page when submitting. This may be freely changed as pages are renamed, etc.
url: This is the local id or url name for the page (without any extension). E.g. "index" for the root page. Used to help auto-triage issues for which a URL is known
workgroup: This is the work group generally responsible for maintaining the page. It only needs to be specified if different from the work group generally responsible for the specification overall (i.e. where different artifacts and pages within the specification fall under the responsibility of different work groups).
deprecated: If set to true, this page will no longer be selectable when submitting new issues or editing previous issues. However, it will still appear on existing issues and be available for use when searching.
otherpage: XML element with 'url' attribute that, if present, identifies the name of additional pages from the specification that are considered to be 'covered' by the root page. For example, if feedback about sub-pages dealing with security are expected to have their issues reported against the 'security' page, grouping the urls for the sub-pages here will allow Jira to automatically categorize submissions with a URL of sub-page as being categorized under the base page instead.