Stream: IG creation
Topic: Jira Spec Artifact Version vs package-list
Gino Canessa (Dec 08 2020 at 19:56):
Hi again all =) Hoping for some guidance before I add something incorrect. In this repo, I'm wondering if I have the version info correct.
It appears I need to add the matching version from package-list.json, but I'm not sure how the URL conventions work. E.g., do I need to create a GH tag STU1 before I push this so that it shows up? Or, is the path wrong and I should create a tag 2021Jan and update the URLs.
Any help/advice appreciated!
Lloyd McKenzie (Dec 08 2020 at 20:15):
Creation of tags should be handled automatically as part of the publication process. You shouldn't have to do anything there.
Lloyd McKenzie (Dec 08 2020 at 20:16):
You will have to specify what you expect the URL to be. For you, it'll be "2020Jan" because it's a ballot release. (The STU1 URL won't exist until you do final publishing.)
Gino Canessa (Dec 08 2020 at 20:29):
Thanks Lloyd, I think (read: hope) that everything's right in the version I just PR'ed then. Cheers!
Sarah Gaunt (Dec 09 2020 at 21:20):
We are having problems getting rid of this warning before ballot:
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/jiraspec.tmp.xml' (currently in Github) and 'jira.xml' (reflects current IG content)
This is in all 3 of our IGs (eCR, BFDR, and VR Common Library). Two of the IGs have never been published before.
The artifacts list and pages and versions appear to be correct (when doing a compare as instructed).
Where does this file live: "'template/jiraspec.tmp.xml' (currently in Github)". Which Github? - we can't find this file. (There is a file created locally (if one builds locally, which I don't) that might be this file?).
We are having problems comparing files and lists because the lists are very long and in different orders etc.
Is there something we are missing as this seems to be a very manual, time consuming, error-prone process. (Especially with large IGs with many profiles, etc.). The process also gets longer/harder based on how many releases the IG has been through.
Any help would be much appreciated as this is the last warning on these 3 IGs we need to get rid of before going to ballot.
Jean Duteau (Dec 09 2020 at 21:24):
You have to take your template/jira.xml and go and make a fork of the JIRA-Spec-Artifacts project, update it with that file (renaming it appropriately for the different projects), and then make a pull request so Lloyd can merge it in.
Jean Duteau (Dec 09 2020 at 21:25):
I'm pretty sure that you will need to build it locally as those files aren't in the output directory so they wouldn't be moved to the build site.
Jean Duteau (Dec 09 2020 at 21:26):
It's not that complex of a thing to do if you are building locally.
Sarah Gaunt (Dec 09 2020 at 21:31):
So the file in the warning message that says "template/jiraspec.tmp.xml' (currently in Github)" - really is NOT in Github and is only local?
Jean Duteau (Dec 09 2020 at 21:32):
it will be in local when the template for your guide is downloaded and expanded
Sarah Gaunt (Dec 09 2020 at 21:49):
Ok thanks.
Maybe that warning message should be updated because it's confusing?
David deRoode (Dec 10 2020 at 01:11):
vr-common-library (https://github.com/HL7/vr-common-library/tree/master) is still getting that warning, yet comparing what is on HL7's Jira spec (https://github.com/HL7/JIRA-Spec-Artifacts/blob/master/xml/FHIR-us-vr-common-library.xml) with what is being built shows zero differences. Might it be some issue with the versioning in package-list.json?
Lloyd McKenzie (Dec 10 2020 at 03:05):
The template/jiraspec.tmp.xml is actually a transformed version of the file from Git that is canonicalized for simpler comparison.
Lloyd McKenzie (Dec 10 2020 at 03:06):
@David deRoode can you send me both files?
Sarah Gaunt (Dec 10 2020 at 04:05):
I just compared my local file and the file in JIRA-Spec-Artifacts and they are indeed identical. I'll send you both files and package-list.json.
Lloyd McKenzie (Dec 10 2020 at 05:16):
Well, it probably didn't help that the message tells you to look at the wrong files... :(
I've fixed the template and it will now tell you to look at the two correct files - the normalized ones it is actually comparing. That should make the differences much more clear. (I've also changed the names of those files so it's more obvious what they contain.) Re-build using the current template. If the issues still aren't clear, send me those files and I'll help further. (Apologies for the confusion thus far.)
Sarah Gaunt (Dec 10 2020 at 06:53):
Ok, maybe that's where we've been going wrong. I'll let @David deRoode take a look in the morning. Thanks @Lloyd McKenzie
Sarah Gaunt (Dec 11 2020 at 00:39):
@Lloyd McKenzie going to send you the new files in email. Some funky stuff going on that we don't understand.
Eric Haas (Dec 11 2020 at 00:55):
as a matter of routine I add the jira warning to the ignorewarnings file. even then it has shown up and I have had to refresh the warnings file
Lloyd McKenzie (Dec 11 2020 at 00:56):
Are you adding warnings from the HTML or from the qa.txt? (You should always populate the ignore file from the latter.)
Eric Haas (Dec 11 2020 at 02:58):
qa.txt
Sarah Gaunt (Dec 11 2020 at 03:04):
Wait - I thought it was mandatory to get rid of the jira spec file warning (i.e. we shouldn't suppress it)...
Jean Duteau (Dec 11 2020 at 03:28):
it needs to be handled at some point. if you suppress just to have no warnings, you'll need to remember that you need to action it before you ballot/publish.
Jean Duteau (Dec 11 2020 at 03:28):
it's so easy to get rid of it or ignore it that I don't see the point in suppressing it
Sarah Gaunt (Dec 11 2020 at 03:43):
"so easy" - @Jean Duteau I'm thinking that's you volunteering to sort out the jira spec issues we are having with our 3 IGs going to ballot this cycle?
Jean Duteau (Dec 11 2020 at 03:44):
Sure. Which ones?
Sarah Gaunt (Dec 11 2020 at 03:45):
BFDR, Vital Records Common Profile Library, and eCR. (I was joking, but I'll take the help!)
Lloyd McKenzie (Dec 11 2020 at 03:45):
You can only 'suppress' it if you've made the determination that the alignment is correct and that what's being proposed by the build process is inappropriate. (Not just because you don't know how to get rid of the warning.) If you suppress it without having done that analysis, the FMG won't let you go to ballot because the drop-downs won't be right for the voters.
Lloyd McKenzie (Dec 11 2020 at 04:07):
I looked at the BFDR IG. I found the following
- the logic wasn't handling determining the default version in cases where there was no official publication. It was choosing the first release (current) instead of the first ballot release. Now fixed.
- the Baby Quinn issue is caused by the fact you have round brackets in your name the text before that is the same as the name of another artifact. The Jira process presumes that if you've got round brackets, you're specifying the 'former' name of the resource. If you replace the round brackets with a dash or something (or better yet, add the word 'example' to the name), that problem should go away. (And no, there's no reasonable way you could have been expected to know that - it was one of those weird edge cases people always manage to find :>)
Sarah Gaunt (Dec 11 2020 at 04:11):
You mean I always manage to find....
Sarah Gaunt (Dec 11 2020 at 04:12):
So I have 3 FHIR IGs. That I thought were finished. They ALL use that same format with the round brackets for examples. I can't fix it right now. I'm still working on one last CDA IG to get to Lynn today. I guess I'll try and sort it all out tomorrow.
Lloyd McKenzie (Dec 11 2020 at 04:19):
Some people just have a special talent
Lloyd McKenzie (Dec 11 2020 at 04:19):
No need to fix it.
Lloyd McKenzie (Dec 11 2020 at 04:19):
At least not right away. It'll save you grief long term if you do.
Lloyd McKenzie (Dec 11 2020 at 04:20):
I'm testing a new validation warning that will let you know what the issue is next time - instead of just doing weird things in your proposed file.
Sarah Gaunt (Dec 11 2020 at 04:20):
I have to fix it - I'm too obsessive to leave it. Sigh.
Lloyd McKenzie (Dec 11 2020 at 04:21):
And some people are just plain special :D
Sarah Gaunt (Dec 11 2020 at 04:21):
Yes, better message would be good.
Jean Duteau (Dec 11 2020 at 04:22):
she's so obsessive she turned down my help to fix the errors. (well that and I don't use Trifolia)
Sarah Gaunt (Dec 11 2020 at 04:23):
I won't fix in Trifolia. I'll fix in Oxygen.
Sarah Gaunt (Dec 11 2020 at 04:23):
I'm also a control freak!
Lloyd McKenzie (Dec 11 2020 at 04:24):
If you take over writing the templates, you could have even more control...
Sarah Gaunt (Dec 11 2020 at 04:24):
And I need to think up a new example naming scheme as clearly my old one is crap.
Lloyd McKenzie (Dec 11 2020 at 04:24):
(I figure it's worth a shot :wink:)
Sarah Gaunt (Dec 11 2020 at 04:24):
HA! Couldn't do that to you, you love it.
Jean Duteau (Dec 11 2020 at 04:24):
use {} or [], I'm sure those special characters won't ruin Lloyd's day
Sarah Gaunt (Dec 11 2020 at 04:25):
Confirm please Lloyd? Can I use []???
Lloyd McKenzie (Dec 11 2020 at 04:25):
They won't. Though having the word 'example' is still a good thing.
Sarah Gaunt (Dec 11 2020 at 04:26):
Ok, here' sthe thing about "example". At some point I DID have that in there. But then on the artifacts page it was coming out with double "example". I think the template was putting it in. That seems to have gone away now though.
Sarah Gaunt (Dec 11 2020 at 04:28):
i.e. I changed them all to NOT have "example".
Sarah Gaunt (Dec 11 2020 at 04:48):
Ok, I did both for BFDR - changed to square brackets AND added "example" to them all.
Lloyd McKenzie (Dec 11 2020 at 04:48):
Ok, build process should capture duplicate names and spit out an obvious warning in the log. (No easy way to get it into the QA though.)
Eric Haas (Dec 11 2020 at 20:19):
I did the Jira thing for both my specs and pushed successfully but still get the warnings, The juice is not worth the squeeze to figure out the warnings, so I suppress.
Jean Duteau (Dec 11 2020 at 20:37):
except that you aren't allowed to suppress the warnings unless there is something explicitly wrong in the tooling that deals with the artifacts file (like there was for Sarah's guides) since that file allows commenters to point their JIRA issue to the proper artifact.
Sarah Gaunt (Dec 11 2020 at 21:03):
Well, up until a day or so ago that warning was meaningless. The files it mentioned didn't even exist. It's changed now, but it's like 2 days before ballot deadline so I'm thinking that might be a valid reason for suppression.
Sarah Gaunt (Dec 11 2020 at 21:05):
I'm suppressing it now anyway, because even after fixing the round bracket issue and adding "example" plus the changes that Lloyd made there still seems to be issues.
Lloyd McKenzie (Dec 11 2020 at 23:30):
@Sarah Gaunt I've tweaked the normalization process to make the comparison slightly easier. The outstanding issues are all things that need to be fixed:
- The ballot URLs are different (different case)
- The ci-build URLs are different (not sure if the one in your json file is wrong or if the one currently in Jira is wrong, but one of the two needs to be fixed
- You're missing a couple of version declarations
- The name of one of your artifacts doesn't jive with what it is in the IG. (I expect you'll want to fix what's in the IG.)
- You're missing the (NA), (many), Artifacts Summary and ToC pages
If you fix those things, then your warning should go away.
Sarah Gaunt (Dec 11 2020 at 23:34):
I haven't been working on the jira stuff and I think @David deRoode is likely finished for the weekend. Does this need to be fixed before Sunday or can it wait until next week?
Sarah Gaunt (Dec 11 2020 at 23:36):
And thanks for the list @Lloyd McKenzie
Lloyd McKenzie (Dec 11 2020 at 23:42):
Getting the missing artifacts in is pretty important. Voters are going to need to be able to say (NA) and (may) in particular. Fixing the URLs is also important because if your ci build is wrong, then the versions page is going to have the wrong link.
Lloyd McKenzie (Dec 11 2020 at 23:43):
FMG hat on, I'd say you need to fix at least those. (And if you're going to do that, then hopefully your OCD will take care of the rest... :>)
Sarah Gaunt (Dec 11 2020 at 23:58):
Of course it will. :joy:
Sarah Gaunt (Dec 12 2020 at 00:58):
Ok, I forked, update, pushed, pulled etc. No idea if I've done this correctly or not, let me know if I totally screwed it up @Lloyd McKenzie
Sarah Gaunt (Dec 12 2020 at 00:59):
One down, two to go...
Lloyd McKenzie (Dec 12 2020 at 02:34):
Merged
Sarah Gaunt (Dec 12 2020 at 02:34):
Thanks! There's one more. Just finishing off eCR...
Sarah Gaunt (Dec 13 2020 at 21:42):
Ok fixed them all yesterday. Thanks for all your help @Lloyd McKenzie
So.... Is there any way this could be made so it's automated based on the jira-current file? I mean, you've already created it - why can't that file just be pushed into the JIRA-spec git each time the IG is built and then it will always be up to date and there won't be this need for manual comparison and updates? (Sean has written code to create the file in ToF but I don't think it takes into account the deprecated stuff.)
Lloyd McKenzie (Dec 14 2020 at 00:34):
Hi Sarah,
What's generated is a suggested starting point. The generation process isn't smart enough to figure out duplicates. And some artifacts we don't necessarily want to list. Some pages we categorize as a single item in Jira even though they have multiple pages. So humans need to be in the loop
Sarah Gaunt (Dec 14 2020 at 00:43):
Darn it!
Rob Hausam (Dec 14 2020 at 02:31):
Since this question is somewhat related, I'll ask it here. Is it suggested to commit the input-cache/jiraspec.xml file, or not?
Lloyd McKenzie (Dec 14 2020 at 02:36):
It's not critical
Last updated: Apr 12 2022 at 19:14 UTC
