-
Notifications
You must be signed in to change notification settings - Fork 4
Revision Management
This article covers overall management of http://profiles.ihe.net, and the use of Publications repository as the management solution.
The http://profiles.ihe.net is the web site where formal technical specifications from IHE will be published. This is distinct from the http://www.ihe.net where other materials including marketing, organizational, and background are published. The two web sites are intended to work together. Generally the http://profiles.ihe.net is intended to only take over for the portion of the http://www.ihe.net that was published as https://www.ihe.net/resources/technical_frameworks/
The profiles web site is a minimal environment, to better enable the IHE domains to dictate exactly how the content is presented. The reason that the profiles web site is needed is the move from publishing PDF as the formal specification, and the move to publishing formal specifications in html form with various other file types as support (e.g. within a FHIR Implementation Guide are xml, json, and other artifacts). The www.ihe.net was not able to meet these needs and is more focused on providing a platform for organizational content that benefits from the platform framework.
The layout of the profiles web site is explained on the Publication layout page.
The IHE Profiles web site content is managed on the Publications github repository. The Publications github repository will be used for gross level revision control, and access to historical content. That is to say that some content will be managed more finely in other ways.
Some content will be managed only within the Publications repository, such as the ITI Technical Framework final-text volumes. This content is considered rather stable, so the changes would be minimal. These changes will typically be driven by formal Change Proposal process. Initially the Change Proposal process will continue as historically done using WORD documents with simple editorial markup, balloted using email and zip files. Once approved these will be applied to Publications with reference to the Change Proposal identifiers. Eventually this may be converted to using GitHub issues, but the Issues likely would need to be managed in a domain specific way, so this would argue that using the Publications repository Issues mechanism should not be used. These are challenges that will need to be addressed in the future.
Some content may be managed in an independent repository; such as supplements, white papers, and Implementation Guide authored content. In these cases the changes are managed in that repository, and only when that content reaches a "ready for publication" like status, will a html output be prepared and submitted as a Pull-Request to the Publications repository with one explanation of why. This pull-request explanation is what I refer to above as "gross". Where the more fine grain details are managed in that independent IHE managed github repository. The pull-request would be initiated by the domain specific committee following that domain's governance process.
The Publications repository will be fluid, taking on changes that are each approved by the appropriate domain. As discussed above these changes would be gross level changes and not fine-grain day-to-day changes. These changes would follow the governance of the domain in which the content is to be published. That is to say changes in the ITI folder should only be approved by the ITI committee. Thus only ready to publish content should be submitted to the Publications repository. The Publications repository should be considered a staging area on behalf of all of IHE. Domains should be careful to submit content that is ready for publication.
The fluid nature of Publications repository means that at anytime it should be ready for deployment onto the [profiles.ihe.net] web site. This is a principle of continuous development / continuous deployment. The github pages mechanism can be used to see this staging at any time - http://ihe.github.io/publications . This site should only be used by committee members, and should not be seen as the formal publication.
Some trigger event, usually a domain committee determining that their folder is ready for publication, will cause the Publications repository to go through a deployment step.
For Publications, there will need to be a decision point made that the content is ready for publication. This is not unlike what is done today on a WORD/PDF basis. Likely similar trigger events will happen with the Publications.
At this point IHE will follow a similar process as we do today with WORD/PDF. There is a review of the changes relative to a set of criteria, including appropriate copyright and crediting. This review makes sure that the content is appropriately marked as a revision as appropriate.
The content will be moved from Publications to Profiles and a check for quality between the IHE staff and the co-chairs of the domains affected.
Any changes that are needed during this deployment step will be reflected back on the Publications repository.
The Publications and thus Profiles are grossly revision tracked, while the content is individually revision tracked. For example the ITI Technical Framework has a version related to the annual revision cycle that is is managed under. However the move of content from Publications repository over to the Profiles web site will be revision managed as well. It is at this level that the revision marking in the Publications repository will be used to tag a snapshot that would be retrievable in the future.
When the content of Publications is moved to Profiles, and after quality checks; then a GitHub "tag" will be created in the Publications repository with explanation of what was released, including the sub-version numbers of any content that was updated.
The GitHub tags will allow committee members and the general public to get a gross change log of changes at that tag relative to the previous tag; and will enable the download of the content as it was at the time of that tagging. This will thus be our mechanism for maintaining an archive.
These tags may be exposed in some way other than the Publications tag user interface. That is not yet decided