Committee review advice for IG publisher projects

This article provides guidance to IHE committees that are developing an Implementation Guide (IHE Profile) using the IG Publisher. It addresses the fact that an IG publication has a different layout and includes guidance on use of GitHub Issues.

Overall Process

The overall process should be considered the same as our historic process for reviewing and maturing an IHE Profile.

• The Supplement Template follows the same layout as has always been used and we want to stick as close to this as possible.
• There are alternatives for manual management of section header numbering, as we have used historically. These header numbers would be managed and assigned in the same way as they would have been with historic WORD/PDF.
  • The main reason to continue using header numbers is to enable logical folding of the Implementation Guide into the domain Technical Framework. The content would still be published in a dedicated folder, but the sections can be easily represented within the broader Technical Framework.
  • ITI has chosen to convert the Final Text Technical Framework to html publication (and html authoring). This makes the logical folding of an IG publication seamlessly.
  • For those domains without a mature Technical Framework, you might choose to not use manual header numbering. This decision is domain specific, and the ramifications have not been discussed at the governance level.
• The same Actor, Transaction, Glossary, and Content management should also be done. There is an other.md/html with the section necessary for publication and harmonization of the Actor, Transaction, Glossary, and Content into broader registry.

Pre-Public Comment

This phase covers the initial writing up to the point that the committee has approved the Implementation Guide for publication. The Publication process is managed by @marylj.

• During this phase, the use of Issues and Pull-Requests are not critical. They can be used, the overhead is often not critical.
• Committee Review
  • Should use the ci-build version that is automatically built every time the GitHub repository is updated. Will be at a URL starting with http://build.fhir.org/ig/IHE
  • Narrative content should be clear, much like we would have done with historic supplements
  • Artifacts should be carefully reviewed, as they represent normative statements
  • QA Report -- found in the footer of the rendered IG -- should have zero errors, warnings, information, or broken links
  • some warnings and information will be reviewed by the committee and determined to be expected. When a warning or information is expected it should be added to the ignoreWarnings.txt with a justification (often groups of warnings have the same justification group them)
  • review the ignored warnings (found in the QA report) to determine that they are indeed justified.
  • Note that the QA report does indicate when no instance of an ignoreWarnings.txt text is found, these tend to be things that got fixed, so the ignore-warning entry should be removed.
  • By getting the QA report to 0,0,0,0 there will be assurances that everything within the IG validates. This includes a minimum that there is an example for any structureDefinition profile.

Public Comment

• Once an IG is published to Public-Comment; this is the point at which all changes to the IG need to be tracked. Thus use of GitHub issues is recommended.
• Determine if your committee and community will be submitting public-comments using GitHub issues. This is enabled with the IG publisher input/data/features.yml. The community members might not have GitHub accounts, which is required to submit an issue. Thus IHE continues to support submitting comments using the historic form and spreadsheet.
• During Public-Comment it is best to not resolve any issues. This because your public might be able to see the issues entered by others and thus chose to not duplicate an issue again.

Trial Implementation and Beyond

• All comments should be resolved using GitHub issues.
• Where many comments are submitted using the comment form or spreadsheet submission; one issue could summarize and point at the tracking spreadsheet.
• Use of GitHub Issues to track all changes enables discovery of why a change was made.
• Use of GitHub Issues and Pull-Requests enables controlled changes with historic provenance
• See Change-Proposal

Change Proposal

• Change-Proposals are encouraged for items that impact the interpretation or conformance.
• Change-Proposal are applied using a GitHub Issue that tracks to the Change-Proposal identifier and resolution
• A Pull-Request is recommended to confirm that the Change-Proposal was applied properly
• The use of Issues and Pull-Requests enable automatic history tracking for the GitHub release tag.

ITI Experience

• Replacing the WORD/PDF/Spreadsheet based Change Proposal with a GitHub Issue/Pull-Request process was tried. This GitHub mechanism is very similar, but we found that our community was not yet comfortable with the use of this.
• Use Issues and Pull-Requests for ALL changes once the content goes Public-Comment.
• Allows comments to be submitted as Issues, as Change Proposals, or the Public Comment form.
  • All of these are assessed.
  • Some are found to be minor and can be processed only as issues. For these kind of issues that were submitted as Change Proposal, we accept the Change Proposal but represent it as a GitHub issue and track that fact in the Change Proposal spreadsheet. Examples are typos, misspellings, mistakes. Some minor things are considered by the committee to be sufficiently impactful that they should be processed as a formal Change Proposal.
  • Some are found to be impactful and thus need the formality and notification of a Change Proposal. This includes issues reported as GitHub issues, which we reflect into a numbered Change Proposal that follows the Change Proposal process, and the GitHub issue is paused until the Change Proposal resolves. The resolved Change Proposal is applied using an GitHub Issue and Pull-Request.