Stream: IG creation
Topic: JIRA warning in IG qa
Brian Reinhold (Mar 11 2021 at 11:37):
@Lloyd McKenzie I get this warning in the QA.html relating to the JIRA specification
The jira specification file appears to be out of date with the versions, artifacts and pages currently defined in the IG. A proposed revised file to be reviewed and, if appropriate, submitted as a pull request against the XML folder in https://github.com/HL7/JIRA-Spec-Artifacts. To see the differences, perform a file compare on 'template/jira-current.xml' (a normalized view of what is in Github) and 'template/jira-new.xml' (reflects current IG content)
Anyone know what it means and how to fix it?
For what its worth I see no difference between my jiraspec.xml and the FHIR-phd.xml in JIRA-Spec-Artifacts. What is out of date? one of the version values in both of the files? I edited my local file to use version 1.0 instead of 0.1 and it got restored to the original when running the publisher. Probably pulled from JIRA-Spec-Artifacts...?
Lloyd McKenzie (Mar 11 2021 at 15:41):
Did you do a diff on the two files it told you to diff?
Brian Reinhold (Mar 12 2021 at 10:05):
@Lloyd McKenzie Where do I find these files? I found the JIRA_Spec-Artifacts project but I have no idea where template/jira-current.xml and template/jira-new.xml are located. I could not find them in the Artifacts project. Where are these two 'template' files? I searched some other projects with the name 'template' in them but that turned out to be barking up the wrong tree. Of course there are many pages of projects and I could not search them all.
I found them in my own project...why would my project have both files and not use the new one? What needs to happen here? Do I need to put the new one in JIRA_Spec-Artifacts? If so, I suppose it is something you have to do or something someone with write access to that repo has to do. If so, I attach the file here. jira-new.xml
By the way, the difference is HUGE which scares me. There are many elements in the 'new' version that are not in the old. It seems like it is much MUCH larger than any of the corresponding files in JIRA_Spec-Artifacts. That does not bode well.
Lloyd McKenzie (Mar 12 2021 at 14:40):
The 'new' file is driven by what artifacts and pages exist in your IG. If you've renamed artifacts or pages, you'll need to adjust the 'new' file to reflect that renaming (keep the key and change the name, possibly also including the old name). You might choose to not expose certain fine-grained artifacts. E.g. you might choose not to allow tracking changes against each individual example, but instead have an 'examples' page. But you do want to ensure that all major artifacts and pages that exist in your IG are represented in Jira and there is continuity between feedback provided in past releases, even as artifacts have been renamed, merged, etc.
Brian Reinhold (Mar 12 2021 at 14:56):
@Lloyd McKenzie How does the new file get generated? I certainly did not do it. And looking through the list it looks like it does list all the 'artifacts' that are in the IG. Is there a reason NOT to include all of them? And if I renamed an example, for example, wouldn't that get automatically updated next build?
Lloyd McKenzie (Mar 12 2021 at 14:57):
The new file is generated by the build process - driven by what's in your IG.
Lloyd McKenzie (Mar 12 2021 at 15:00):
The reason to not include them is if you feel the fine-grained list would be overwhelming. For example, with core, we don't list every single example or search parameter because we'd have 10k+ artifacts. For IGs, that's less of a problem, but could still be too much. Similarly, some pages get 'grouped' and are treated as a single 'page' from the perspective of tracking feedback. Your key question is "how, as a work group, do you want feedback against your IG to be categorized?"
Brian Reinhold (Mar 12 2021 at 15:10):
So I guess I would have a better understanding of this file if I went through the process of reporting a bug or something like that on this IG. I am not sure how to do that. I see the usual propose a change option, but that brings me to the generic FHIR issues page. I would think it would be easier to find the issue the more 'detail' one has - so one can home into the problem. Of course, I have no idea what I am talking about as I have never submitted an issue against an IG.
Lloyd McKenzie (Mar 12 2021 at 15:12):
From the generic FHIR issues page, fill in the 'specification' to be your IG. That then determines what artifacts, pages and versions are available in the other dropdowns.
Brian Reinhold (Mar 12 2021 at 15:21):
@Lloyd McKenzie I actually tried to do that, but I did not find my IG in the list. I did find Personal HealthCare Devices but I do not think that is the IG - it only has a version of 0.1 (probably a default). It might be because this IG has never been published.
Lloyd McKenzie (Mar 12 2021 at 15:29):
If it's gone to ballot it'll be in Jira. Why do you think "Personal Healthcare Devices" isn't the IG?
Brian Reinhold (Mar 12 2021 at 15:42):
@Lloyd McKenzie Its version was 0.1 (it was 1.0.0 at ballot) and I could not find any artifacts. All my entries return nothing found.
Wait a second, that's what's in the phd file in the JIRA-artifacts file. There are no artifacts in that file and its also 0.1. That's why I am finding nothing. So I need that updated file to replace the PHD version of the template in the JIRA-Artifacts directory. Then I should find something.
Lloyd McKenzie (Mar 12 2021 at 15:46):
It should not have been 1.0.0 at ballot - that would have been the publication release number, not the ballot release number.
Correct - that file is what determines what's available in the Jira dropdowns for people to provide feedback. (And that's why the build process now hollers if it appears there's content in your IG that isn't listed in Jira)
Brian Reinhold (Mar 12 2021 at 16:08):
@Lloyd McKenzie Okay, maybe it wasn't 1.0.0 at ballot. Was probably current. But then I need to have that updated file installed in the artifacts list. I assume that it can always be changed once we have some experience. To be honest with you, I had no idea such an infrastructure existed for IGs.
Lloyd McKenzie (Mar 12 2021 at 16:10):
Once you add an artifact or page, you can't remove it (easily) because someone might have referenced it in Jira, so in general it's best to be cautious about what you add, because once it's in a Jira dropdown, it's there forever. You can deprecate - which keeps people from selecting it on new issues, but you can't easily get rid of stuff that might have been used on old issues.
Brian Reinhold (Mar 12 2021 at 16:16):
@Lloyd McKenzie Okay, better have a discussion about that in DoF. It would be good for them to know about this as they will have the same situation arise when its time to publish the PoCD. At least I know what all this means. Learn something new every day!
Bryn Rhodes (Apr 08 2021 at 21:16):
@Lloyd McKenzie , I thought that the templated IGs generated this file, but I can't find it? Is there a parameter I need to set to turn on generation?
Jose Costa Teixeira (Apr 08 2021 at 21:19):
@Bryn Rhodes are you using an HL7 template? Only those use the Jira stuff
Bryn Rhodes (Apr 08 2021 at 21:24):
Yes, hl7.fhir.template
Lloyd McKenzie (Apr 09 2021 at 04:24):
Do you have a package-list.json file? You won't get a Jira file unless/until you have a package-list.json
Bryn Rhodes (Apr 09 2021 at 15:53):
I do, in the root of the directory (same place as the ig.ini), but I haven't added the entry for the version we're publishing, I'll try that.
Bryn Rhodes (Apr 09 2021 at 16:00):
What is the relationship between the package-list.json in the root and the data/packagelist-list.yaml
Bryn Rhodes (Apr 09 2021 at 16:00):
Is the tooling aware of the packagelist yaml?
Bryn Rhodes (Apr 09 2021 at 16:01):
(Other than making it available through the sitedata variables)?
Bryn Rhodes (Apr 09 2021 at 16:01):
@Eric Haas
Lloyd McKenzie (Apr 09 2021 at 16:37):
No clue what packagelist-list.yaml is. Is that a FSH thing?
Jean Duteau (Apr 09 2021 at 16:40):
nope, not a FSH thing
Lloyd McKenzie (Apr 09 2021 at 16:42):
Then the yaml file shouldn't exist and you should be authoring and editing the package-list.json file directly.
Bryn Rhodes (Apr 09 2021 at 17:36):
Okay, I've got an updated package-list and building with templates, but I still don't see the JIRA Spec artifact file. Where does it get generated?
Lynn Laakso (Apr 09 2021 at 17:45):
@Lloyd I see you merged his PR but how does the update get into Jira then?
Lloyd McKenzie (Apr 09 2021 at 18:15):
When the PR is merged into the main build, there's an automatic process that pushes "built" content into a separate branch. Jira grabs the list of elements from the XML file exposed on that separate branch
Eric Haas (Apr 09 2021 at 18:16):
@Bryn Rhodes the data/package-list.yaml is to enable references to the package-list within the ig and is not used for validation. In the guides I author, I typically set it up to have both ig.yaml and package-list.yaml in the data folder using a bash script to refresh the ig.yaml file. The package-list is manually updated in real time as I apply trackers to create a change log which is published in the blue information box in the home page. for example see here: This helps reviewers qa the applied trackers. Prior to publishing the package-list.yaml is converted to a json file and the blue box removed.
Bryn Rhodes (Apr 09 2021 at 18:18):
Thanks Eric! Yes, we adopted your styling for the QM IG (because it's fantastic), so we are using that same approach, and I've just then updated the package-list.json manually. (http://build.fhir.org/ig/HL7/cqf-measures)
Lloyd McKenzie (Apr 09 2021 at 18:18):
I think it'd be cleaner to have the template process copy the package-list.json file into the temp/pages/_data folder - no need to have a yaml file (or remember to run custom bash scripts)
Bryn Rhodes (Apr 09 2021 at 18:19):
I agree, I don't like having that content in multiple places, so if there's a way that can be automated, that would be great.
Eric Haas (Apr 09 2021 at 18:22):
@Lloyd McKenzie For me editing in Yaml is easier and more intuitive. converting to and from json is single click on my editing or a single line in my bash. It is automated for me and I am not advocating or mandating everyone does it the same way.
Eric Haas (Apr 09 2021 at 18:22):
json, yaml or csv all work in the data files, I like yaml
Eric Haas (Apr 09 2021 at 18:27):
Right now this is a manual process, but we have discussed before the automation of the change logs , maybe by adding a couple of fields to Jira and doing an export into the ig. The fields are summary of change and reference to change in the spec.
Lloyd McKenzie (Apr 09 2021 at 18:28):
The problem is if someone comes along and fixes something in your IG, they're going to edit the json file - and may not even realize the yaml exists. And you'll then wipe their fix the next time you run the bash script. We're trying to make our IGs so that anyone who knows how to edit IGs can feel comfortable editing any IG.
Eric Haas (Apr 09 2021 at 18:32):
same problem with fsh. So I don't see why this is any different
Lloyd McKenzie (Apr 09 2021 at 19:14):
FSH is an official HL7 standard and is used by many HL7 IG authors (eventually, I expect it'll be used by most). It also offers a bunch of features that make it significantly faster and easier to create and maintain IGs. I don't think we can make the same argument here for yaml vs. json for the package-list.json. If you feel strongly that there's a serious benefit to moving to yaml, then we should have that as a discussion and do it for everyone.
Bryn Rhodes (Apr 09 2021 at 19:22):
Back to the issue at hand though, I'm still not seeing the generated JIRA spec artifact file, am I looking in the wrong place?
Lloyd McKenzie (Apr 09 2021 at 21:52):
Should be in the root folder of your IG. What's the Git URL? I can take a look if you like
Bryn Rhodes (Apr 11 2021 at 20:30):
I see the issue, it is looking in the JIRA-Spec-Artifacts github for FHIR-us-cqfmeasures.xml, but the file in github is named "FHIR-us-qm.xml"
Bryn Rhodes (Apr 11 2021 at 20:30):
So it gets an error trying to download and doesn't generate.
Lynn Laakso (Apr 11 2021 at 20:58):
so the https://confluence.hl7.org/display/HL7/Configuring+Specification+Feedback page says that 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' to your ImplementationGuide resource (under 'definition'), with a value of whatever the 'Code' is in Jira.
Bryn Rhodes (Apr 11 2021 at 23:07):
Perfect, that did it, thank you @Lynn Laakso
Last updated: Apr 12 2022 at 19:14 UTC
