Stream: ig publishing requirements
Topic: Publisher & template change process
Lloyd McKenzie (Aug 24 2021 at 02:15):
The draft process for making changes to the HL7 FHIR IG Publisher that affect the appearance of IGs or the authoring actions of IG creators, as well as changes to the IG templates that are maintained by HL7 (including the base template, the HL7 template, the product family templates and the HL7 accelerator templates) can be found here: https://confluence.hl7.org/display/FHIRI/Publisher-impacting+Change+Process
We'll be discussing these changes on our regular call on Tuesday, 6 Eastern. Discussion and feedback also welcome here on Zulip. After a few iterations, we'll be seeking feedback and approval for these processes from the various management groups and possibly others.
Vassil Peytchev (Aug 24 2021 at 12:44):
This proposal assumes there will be only a single, rolling release. Has it been considered whether different releases (with different release branches) may need to be maintained? I think an example may be IGs against R4 vs IGs against R5 or R5+ might need to look/be built differently.
Lloyd McKenzie (Aug 24 2021 at 13:30):
So far, we have no requirements identified to publish different IGs differently. Are you aware of any requirements that would drive us to need to do that @Vassil Peytchev?
Brett Marquard (Aug 24 2021 at 14:21):
A rolling release can be difficult to track -- did you consider a set release 1-2 times a year? I haven't been tracking super close, but I would hope the design would stabilize
Lloyd McKenzie (Aug 24 2021 at 14:34):
Given the backlog of requested changes (and limited volunteer resources), I wouldn't expect stabilization for a couple of years. The less frequent the 'official' resources, the more you'll lose in terms of new functionality if you have to move back to a prior release.
Lloyd McKenzie (Aug 24 2021 at 14:35):
Current proposal is 3 times a year, aligned with WGMs, as that minimizes impact on ballot - and gives lots of lead time if there are issues.
Lloyd McKenzie (Aug 24 2021 at 14:35):
Do you think there's a significant benefit to dropping to only one release a year? (2 releases a year are hard to align to ballot cycle)
John Moehrke (Aug 24 2021 at 14:45):
I think this is a good intended goal. I think your point on the number of requested changes and lack of skilled help; puts us a bit at a disadvantage. i don't think we will be mature enough to hit this goal for a couple of years (if ever).
Jose Costa Teixeira (Aug 24 2021 at 14:47):
a lower release frequency would likely make the development also slower
Brett Marquard (Aug 24 2021 at 14:49):
Sometimes slow is ok...unless something is broken!
Vassil Peytchev (Aug 24 2021 at 14:50):
I don't have any specific requirements for different versions. One thing that may benefit from the existence of different versions is that there are IGs that are based on a specific FHIR version, have their own stable version, and I see no need for them to be updated with new publisher or template changes. AFAIK, currently any change to the IGPublisher (and I assume to the templates) is applied to al existing IGs.
Brett Marquard (Aug 24 2021 at 14:54):
Do you think there's a significant benefit to dropping to only one release a year? (2 releases a year are hard to align to ballot cycle)
In terms of number, to me it's about engagement -- if you want a broad community to review, less releases with fixed review times is better IMHO. The continuous potential change is quite hard to engage unless you make it a full time part of someone's role -- and I suspect most IG publishers don't have time to.
John Moehrke (Aug 24 2021 at 14:54):
definitely a tradeoff, and a tradeoff that we are right now trying to predict the importance of the future. If that future issue is something like the need to change an icon or footer for an urgent trademark or copyright reason; doing it universally and fast is important. If it is adjusting the shade of red, less important.
Brett Marquard (Aug 24 2021 at 14:54):
I appreciate you working to formalize the change process
John Moehrke (Aug 24 2021 at 14:55):
the fact that projects can further refine/customize has kept this discussion out of the lime-light. It is the formal improvement of universal and hl7 templates that is the focus of the need.
Jose Costa Teixeira (Aug 24 2021 at 14:55):
I tend to disagree on slower being better here. If someone doesn's review in 4 months, I don't think they'll review in 1 year.
Jose Costa Teixeira (Aug 24 2021 at 14:57):
I do think that to facilitate review, we should also have some documentation - which is in the process, so that we can tell people what the changes are, and we provide examples of those changes
John Moehrke (Aug 24 2021 at 14:58):
I fully expect the "norm" will be ignorance until after something is deemed by someone as bad (e.g. like the pre/next change). This doesn't seem optimal, but I think it is the "norm" given that we are all very much focused in our own little world most of the time.
John Moehrke (Aug 24 2021 at 14:59):
a focused few people WILL be actively engaged and reviewing as part of the quality release process. Most people will not.
Brett Marquard (Aug 24 2021 at 15:04):
I do think that to facilitate review, we should also have some documentation - which is in the process, so that we can tell people what the changes are, and we provide examples of those changes
This is great. I am concerned saying folks need to be ready to review continuously will mean it gets ignored by all but a few....And sure, slow shouldn't be a goal, but stable needs to be.
John Moehrke (Aug 24 2021 at 15:06):
but it is not continuously. it is " (tri-annually post ballot "
Lloyd McKenzie (Aug 24 2021 at 15:07):
@Vassil Peytchev If you're making a technical correction to an old IG, it would make sense to publish with the template release you originally published under. If you're doing a new ballot or new release, then the expectation would be that you'd publish using the current template. (And in all cases, you'll need to publish using the current publisher.)
John Moehrke (Aug 24 2021 at 15:08):
which begs the point... what template version was used... we need this recorded in the qa report
Lloyd McKenzie (Aug 24 2021 at 15:08):
That's a logged requirement
John Moehrke (Aug 24 2021 at 15:09):
(I knew that, just wanted that noted given the current discussion)
Lloyd McKenzie (Aug 24 2021 at 15:13):
The proposed process should ensure that changes are publicly surfaced with opportunity for feedback before they're implemented. Those who have strong feelings on what IGs should/shouldn't look like would be expected to monitor that as it's inefficient to only get feedback once something has been implemented and rolled out, many IGs are already using it, and at the end of the year, someone says "I don't like this, roll it back". The evaluation of proposed changes and evaluation of changed design is, by definition, going to be continuous. The release into 'current' is to give some experience with a wider range of IGs so that if there are implementation issues, they can be identified and addressed. Doing an 'official' release is to set the expectation that everyone should now be using the new thing.
Vassil Peytchev (Aug 24 2021 at 16:29):
The requirement the you use the current publisher with an older version of the templates is what I think might become old pretty soon. I guess we will know if you hit that problem.
John Moehrke (Aug 24 2021 at 17:10):
I think the intention is that majority of everyone uses current... but if you are building an old spec, you will likely want to build using the template version that was use back originally.. and I point out that if you used current back then, you would not necessarly know which version was used. Clearly if you always use a versioned template then it is known, as it is in your configuration files checked into your github; but then you are not taking advantage of current
Lloyd McKenzie (Aug 24 2021 at 17:50):
The CI build is locked to 'current' publisher. We'd need a good reason to change that. And occasionally, the publisher is locked to external interface changes (package server, terminology server, etc.) So even if you might want to use an old publisher, that might no longer be possible.
Lloyd McKenzie (Aug 24 2021 at 17:50):
If we had a strong reason to publish using an old publisher, we might be able to make it happen sometimes, but it's unlikely to ever be the default behavior.
John Moehrke (Aug 24 2021 at 17:51):
I was not expecting the ci build to do that.. I was thinking of the process used to create a formal publication, which is local build.
Lloyd McKenzie (Aug 24 2021 at 17:55):
The issue is that review is always against the CI build
Lloyd McKenzie (Aug 24 2021 at 17:55):
So we'd need some sort of alternate review process
John Moehrke (Aug 24 2021 at 17:56):
yes. different topic of review vs it is possible to build to a specific version
John Moehrke (Aug 24 2021 at 17:57):
messages seemed to cross. I am in the camp of CI build is the right place for 'current' and improvements on template
John Moehrke (Aug 24 2021 at 17:58):
picking a version is the domain of formal publications
Lloyd McKenzie (Aug 26 2021 at 04:04):
See here: https://chat.fhir.org/#narrow/stream/179252-IG-creation/topic/Multipart.20IGs for an example of a fix that affects rendering, and isn't a technical correction, but certainly isn't something that should require deep review and discussion.
Grahame Grieve (Aug 30 2021 at 07:21):
another one, here: https://chat.fhir.org/#narrow/stream/179252-IG-creation/topic/Logical.20Model.20Examples
Lloyd McKenzie (Sep 08 2021 at 02:43):
Here's an updated version of the process. If there's no feedback on this one, we'll then pass it on to the broader community and various governance bodies: https://confluence.hl7.org/display/FHIRI/Publisher-impacting+Change+Process
Craig Newman (Oct 01 2021 at 20:07):
Per FHIR-I's request, the v2 Management Group reviewed the Change Process Confluence page and added some comments there for consideration. We plan to discuss this further on our call next week (Friday Oct 8th). Thanks.
Last updated: Apr 12 2022 at 19:14 UTC
