Stream: IG creation
Topic: Create history page with FSH
Jorge Mansilla (Jan 11 2022 at 22:51):
Dear all,
I try to create a page with history of version of my IG, but I cant create, I dont know how to do it! I want to create like this example of USCORE guide image.png ( http://hl7.org/fhir/us/core/history.html )
I hope that you can help me.
My IG is https://hl7chile.cl/fhir/ig/CoreCL/
Best from Chile
Grahame Grieve (Jan 11 2022 at 23:28):
you can't do that
Grahame Grieve (Jan 11 2022 at 23:29):
the history page is special - it's not built as part of the IG. I'll document how it's built
Thomas Tveit Rosenlund (Jan 15 2022 at 22:52):
Grahame Grieve said:
the history page is special - it's not built as part of the IG. I'll document how it's built
@Grahame Grieve Where will this be documented?
A related question. For some reason. The IG's built by IG-publisher docker image does not get a link to the history page by default only this:
image.png
Is this a template thing or some other problem?
Grahame Grieve (Jan 15 2022 at 23:26):
Grahame Grieve (Jan 15 2022 at 23:30):
The IG's built by IG-publisher docker image does not get a link to the history page by default only this:
umm, what's the IG publisher docker image?
Jose Costa Teixeira (Jan 16 2022 at 08:37):
I think this is the same isue:
https://github.com/HL7/fhir-ig-publisher/issues/353
Thomas Tveit Rosenlund (Jan 16 2022 at 08:56):
Grahame Grieve said:
The IG's built by IG-publisher docker image does not get a link to the history page by default only this:
umm, what's the IG publisher docker image?
Thanks for the link to the documentation.
We use the docker://hl7fhir/ig-publisher-base
I think it is the one and only, and somewhat official? Although it is not mentioned by the docs? (I can't find it using search on HL7 confluence).
Thomas Tveit Rosenlund (Jan 16 2022 at 08:58):
Jose Costa Teixeira said:
I think this is the same isue:
https://github.com/HL7/fhir-ig-publisher/issues/353
Agreed, looks like the same issue @Jose Costa Teixeira
Grahame Grieve (Jan 16 2022 at 21:14):
well, I don't know anything about the docker, but that behaviour you are talking about is by design.
Jose Costa Teixeira (Jan 16 2022 at 21:25):
How can we get the publisher to keep pointer to the github repo when it's running on a cloud somewhere?
Jose Costa Teixeira (Jan 16 2022 at 21:28):
there's 2 things, I may have mixed them:
- the publisher running on the cloud says it's local. I think that should not be.
- The "this will be filled by the publication tooling" - @Thomas Tveit Rosenlund this means there's a step missing/incomplete (the publication). So not the same thing.
Grahame Grieve (Jan 16 2022 at 21:31):
when you say 'running in the cloud', what do you mean? What makes it local is context, and it's context is local to where ever it is running, unless it is given information differently
Grahame Grieve (Jan 16 2022 at 21:32):
the step missing is the one I documented
Jose Costa Teixeira (Jan 16 2022 at 21:32):
cloud: running it in a github action.
Jose Costa Teixeira (Jan 16 2022 at 21:33):
context will be whatever box it's running on (the gh gloud linux machines, in this case). Can we provide that context somehow to the publisher?
Jose Costa Teixeira (Jan 16 2022 at 21:35):
Grahame Grieve said:
the step missing is the one I documented
Yes. @Thomas Tveit Rosenlund I believe this will also fill in the history page (if the history page you mention is like this for example )
Jose Costa Teixeira (Jan 16 2022 at 21:36):
the publisher running from a github action is not the same as running on a local machine (that may not even have a github repo)
Jose Costa Teixeira (Jan 16 2022 at 21:41):
(let me try something)
Grahame Grieve (Jan 16 2022 at 21:45):
context will be whatever box it's running on
well, that would be like the auto-build, but why not just use the auto-build set up?
Grahame Grieve (Jan 16 2022 at 21:46):
I believe this will also fill in the history page
well, actually, what @Thomas Tveit Rosenlund asked about was filling the reference to the history page, not the actual history page. That's called the publish box
Jose Costa Teixeira (Jan 16 2022 at 21:52):
Grahame Grieve said:
context will be whatever box it's running on
well, that would be like the auto-build, but why not just use the auto-build set up?
I can't find the thread, there's some discussion on using the auto build but not hosting on build.fhir.org/ig
Jose Costa Teixeira (Jan 16 2022 at 21:52):
I'm using that, and a couple other projects/orgs are doing that.
Grahame Grieve (Jan 16 2022 at 21:53):
yes well, that autobuild only hosts on build.fhir.org, but why not do that?
Jose Costa Teixeira (Jan 16 2022 at 21:53):
(that's the thread that I lost)
Jose Costa Teixeira (Jan 16 2022 at 21:55):
It seems that the publisher assumes the auto-build paths https://build.fhir.org/ig/xxx/yyy and https://github.com/xxx/yyy
Grahame Grieve (Jan 16 2022 at 21:57):
yes that's exactly right
Jose Costa Teixeira (Jan 16 2022 at 22:02):
I have my own github workflows setup. It allows me to manage my branches (and supports main instead of master), and I can do other stuff in there.
Grahame Grieve (Jan 16 2022 at 22:04):
will, good for you, but the Ig publisher won't support that out of the box. I'm finding this conversation is hopelessly confused between ci-build and publication release
Jose Costa Teixeira (Jan 16 2022 at 22:06):
Well, I did mistakenly put the other issue here. You're right.
Jose Costa Teixeira (Jan 16 2022 at 22:07):
I think the other issue should still be looked at but i'll separate the discussion.
Grahame Grieve (Jan 16 2022 at 22:16):
for review:
Grahame Grieve (Jan 16 2022 at 22:16):
https://github.com/HL7/fhir-ig-publisher/pull/371/files
Grahame Grieve (Jan 16 2022 at 23:07):
@John Moehrke @Jose Costa Teixeira @Oliver Egger
The IHE naming pattern creates a challenge for me. At present, in the publication process, everything is inferred from the package name. canonicals, urls, folder layouts.
But the scheme you've outlined, where the canonical is https://profiles.ihe.net/${domain}/${profile}... well, that's not quite true, since the domain and profile name are partially uppercased. There's no algorithm for that, since it's based on the name of the profile.
Grahame Grieve (Jan 16 2022 at 23:07):
other than that, this should all be good to go now
Thomas Tveit Rosenlund (Jan 17 2022 at 08:16):
Grahame Grieve said:
the step missing is the one I documented
So if I got a package manifest it should fill in the publish box?
Jose Costa Teixeira (Jan 17 2022 at 08:36):
No, you have to run through the entire publication process
Jose Costa Teixeira (Jan 17 2022 at 08:36):
(which is just one step, but having the right folders and files in place)
Jens Villadsen (Jan 17 2022 at 08:50):
Just passing by here - my two cents regaring supporting building IG's not on build.fhir.org - that is definetly a thing. There may be a varity of reason for people wanting to host the building themselves - whether it is in GH actions, custom Gitlab setups or something that might not be ready for public eyes. The main reasons for me to use both the build.fhir.org, github actions and other proprietary setups is that I value that I can specify exactly when I would like to bump versions of eg. the publisher and FSH. In the build.fhir.org infrastructure, I have no such control. I also need to be able to be independant of the build.fhir.org being down for maintenance due to contractual reasons. As such, I consider it 'a normal' scenario being able to build the IG on other infrrastructure than the build.fhir.org
Grahame Grieve (Jan 17 2022 at 11:39):
well, keep in mind that you won't always have control elsewhere, since occasionally IG Publisher releases are forced on me by changes to the underlying infrastructure mean it won't run anymore
Grahame Grieve (Jan 17 2022 at 11:42):
however: I'm not opposed to supporting GH Actions etc, I just really prefer people use the standard ci-build for two reasons:
- Every configuration option is another permutation of possibilities I have to defend on an ongoing basis
- I really like IGs to be registered here: https://fhir.github.io/auto-ig-builder/builds.html
But this is only 'prefer', it's not necessary. The only thing I insist is that if people want to me and the team to support non-public repositories, we only do it for $$. I was going to say that we're not running a charity here, but we are, just not in that direction.
Anyway @Jose Costa Teixeira and I talked about it and he's going to make a PR that fixes a known issue for using IG publisher for GH actions
Grahame Grieve (Jan 17 2022 at 11:43):
@Thomas Tveit Rosenlund the -publish option is only for use inside the whole publication process. It sets up the IG for publication, but the actual publication is as documented in that link above. Though you can do all the things that the IG publisher does manually, or in your own script, if you want to do things differently.
(and people always want to do things differently. Sometimes for not really good reasons, and sometimes for good reasons)
Jens Villadsen (Jan 17 2022 at 13:19):
@Thomas Tveit Rosenlund you should know that @Jose Costa Teixeira has scripted a lot of the process at https://github.com/costateixeira/testrel/blob/master/release.py
Jens Villadsen (Jan 17 2022 at 13:20):
That is the script I use for the DK Core release procedure
Jose Costa Teixeira (Jan 17 2022 at 13:22):
Hold on there(if you can). I may have to redo that one given the latest changes to the publisher. AND this script is intended to be used with some process around this - i.e. making a release is a formal process that needs humans. Even if the release build is automated to save some work
Thomas Tveit Rosenlund (Jan 17 2022 at 13:41):
Jose Costa Teixeira said:
Hold on there(if you can). I may have to redo that one given the latest changes to the publisher. AND this script is intended to be used with some process around this - i.e. making a release is a formal process that needs humans. Even if the release build is automated to save some work
Thanks for the input @Jose Costa Teixeira @Jens Villadsen
We are currently testing a new release process for the HL7 Norway released profiles. Currently we release things through SIMPLIFIER, but they are not perfectly integrated in the HL7 release process. I think the only place we show up is in the package registry. Everything else is strictly manual labour. We would want to establish a more automated build and release process for our IG's that integrate better with what the rest of HL7 and affiliates are doing.
We will consider both a tailored process based on GitHub actions, but also just using the auto-ig builder like @Grahame Grieve suggests as I am not sure we need all the flexibility of a tailored process. However, some of the IG's published by vendors and healthcare organizations in Norway could benefit from a more "lax" build/publish process. It is quite a learning curve for us that have grown accustomed to the SIMPLIFIER process however.
Sorry for all the stupid questions. Grahame was right, removing the -publish (undocumented?) option on the IG publisher command line did the trick, and without this set, the content of the publish box and link to a history page is back. I am still not sure how to get the correct content into the publish box for a published release build, as I find the documentation on this part of the process rather confusing.
Jose Costa Teixeira (Jan 17 2022 at 13:55):
That (the confusing part) is what we're working on
Thomas Tveit Rosenlund (Jan 17 2022 at 18:17):
Jose Costa Teixeira said:
That (the confusing part) is what we're working on
That sounds great @Jose Costa Teixeira, would love to see a bit clearer documentation and a more automated workflow for publishing new releases of an IG.
Grahame Grieve (Jan 17 2022 at 19:37):
I am still not sure how to get the correct content into the publish box for a published release build, as I find the documentation on this part of the process rather confusing.
the point is that 'correct' depends on what the release process is. The documentation describes the setup that the IG publisher expects, and how to do a release. Can you be specific about what is confusing?
Thomas Tveit Rosenlund (Jan 17 2022 at 21:43):
Grahame Grieve said:
I am still not sure how to get the correct content into the publish box for a published release build, as I find the documentation on this part of the process rather confusing.
the point is that 'correct' depends on what the release process is. The documentation describes the setup that the IG publisher expects, and how to do a release. Can you be specific about what is confusing?
I would expect to find information about where or how the history page should be maintained. Either in the IG-publisher doc or the Guidance for FHIR IG Creation.
The history page is mentioned in the documentation of the deprecated control file, but othervise there is not much said about how inclusion or exclusion affects the build process or how to maintain that. But I finally found this page describing how to build a history page. It might be linked from the aforementioned pages, but I have not seen that.
Grahame Grieve (Jan 17 2022 at 21:45):
well, that documentation is wrong
Grahame Grieve (Jan 17 2022 at 21:46):
the history page is maintained automatically as part of the publication process
Yan Heras (Feb 08 2022 at 18:54):
The changes I made to package-list are not shown in the CI build history page. My build was successful and changes to other pages were shown fine in the CI build. I first updated to use descmd to add more change details for a version. Those changed were not picked up in the history page of the CI build. I then changed it back to use desc with minor editing words from the January balloted version of package-list, the CI build still shows the exact same content from the Jan ballot history page. Are there anything else that I need to do? or are there any issues with the history page auto-build?
Chris Moesel (Feb 08 2022 at 19:07):
I think that package-list is only used at time of publication (not time of build).
Yan Heras (Feb 08 2022 at 19:26):
Thanks Chris. So if I want to use descmd to add detailed change logs (e.g., which trackers were applied) to history page, how do I test out if get them entered/formatted correctly before official publication?
Bryn Rhodes (Feb 08 2022 at 19:47):
If you look at CQF Measures ballot, there is an example of putting that list of changes in the home page.
Bryn Rhodes (Feb 08 2022 at 19:48):
https://github.com/HL7/cqf-measures/blob/v2.1.0/input/pages/index.md?plain=1#L9
Bryn Rhodes (Feb 08 2022 at 19:48):
https://github.com/HL7/cqf-measures/blob/v2.1.0/input/data/package-list.yml
Bryn Rhodes (Feb 08 2022 at 19:49):
Not sure that really constitutes a "test" of package-list.json, but it's a start.
Grahame Grieve (Feb 08 2022 at 20:07):
you can test your descmd content using any standard commonmark editor
Yan Heras (Feb 08 2022 at 21:01):
Thank you all for your help.
Last updated: Apr 12 2022 at 19:14 UTC
