Stream: IG creation
Topic: Jira Spec file out of date
Nathan Davis (Aug 24 2021 at 14:27):
@Lloyd McKenzie @Jean Duteau I'm getting this error:
warning 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)
Why am I getting this? I haven't touched this file since creating the pull request. And, how do I update it? I've looked at the two files (current and new) and don't wish to use the new file.
Jean Duteau (Aug 24 2021 at 14:28):
you have to use the new file. The file is created based on what your IG actually has. If you don't like what the new file says, then you need to look at the artifacts you have in your guide and see why.
Jean Duteau (Aug 24 2021 at 14:29):
basically, what did you change in your Guide since the last time you ran the publisher? That change has resulted in either a new artifact, a change in an existing artifact name, or a deprecation of a removed artifact.
Lloyd McKenzie (Aug 24 2021 at 14:31):
Changing version information will also trigger the Jira file being out of date
Nathan Davis (Aug 24 2021 at 14:32):
So, rename the new one, replace the old one, and create a pull request?
Nathan Davis (Aug 24 2021 at 14:32):
Or something along those lines.
Nathan Davis (Aug 24 2021 at 14:33):
talking about the Jira Spec file.
Jean Duteau (Aug 24 2021 at 14:34):
yeah. i tend to wait until I think i'm done with my changes and am ready to be published. as I said above, any change to the list of artifacts will cause a need for a new spec file to be uploaded, so when the changes are complete is when I do it.
Nathan Davis (Aug 24 2021 at 14:35):
Yes, will definitely make all changes first.
Thank you!
Nathan Davis (Aug 26 2021 at 18:18):
I'm still getting the Jira Spec file out of date warning. However, the only difference between current and new is that the new file is leaving the value of defaultWorkgroup null.
defaultWorkgroup = ""
I need it to have the value of "cimi". Is there a configuration setting I'm missing somewhere?
Lloyd McKenzie (Aug 26 2021 at 18:23):
The first contact url for your IG needs to be "http://www.hl7.org/Special/committees/cimi"
Nathan Davis (Aug 26 2021 at 18:29):
Thank you. I had it set to http://hl7.org/Special/committees/cimi/index.cfm
Brian Reinhold (Oct 14 2021 at 19:37):
@Lloyd McKenzie I am getting the same error but the only place I see the file is in the 'input-cache' directory. I thought the content of all the other directories was generated and I should not touch those. I have not created one myself. Do I need to do that? If so, where do I put it?
Jean Duteau (Oct 14 2021 at 20:41):
you don't see jira-current.xml and jira-new.xml in the template directory?
Jean Duteau (Oct 14 2021 at 20:42):
if you can provide us with a link to your repository, we can help better
Brian Reinhold (Oct 14 2021 at 20:57):
@Jean Duteau
I do not, but then again I have not fetched from the repo, I have just built everything locally and pushed. In any case, I did not think that I should modify anything except that which appears in the 'input' directory.
Jean Duteau (Oct 14 2021 at 20:58):
it's not asking you to modify anything in your repo. it's saying that you need a jira specification file in the JIRA-Spec-Artifacts project and/or that your project's artifacts do not match what is in that project.
Jean Duteau (Oct 14 2021 at 21:01):
Brian Reinhold said:
I do not, but then again I have not fetched from the repo, I have just built everything locally and pushed.
After you build locally, you will have a template directory. In that template directory will be what is in the JIRA-Spec-Artifacts for your project and what it should be based on the changes you've made to your guide. All this warning is telling you is that either a) you need to make an entry for your project in the JIRA-Spec-Artifacts project if this is a new guide or b) you need to update the file in that project because of the changes you have made.
Brian Reinhold (Oct 14 2021 at 21:07):
Okay,
I am quite lost. My project is very old; it was one of the early ones and it was set up and configured for me by Grahame. I did not have permissions to do the necessary things that were needed. Since then all I have done is add content. I used Lloyd's framework for quite a while and just recently (about a year ago) moved to the current common framework. That was not a lot of work as the two were quite similar.
It sounds like the JIRA-Spec-Artifacts is something that is beyond just my IG, and I am sure to have no access rights to that file where ever it is. IN any case, there is no such file in my home repository.
Lloyd McKenzie (Oct 14 2021 at 22:35):
The file in your home directory won't be called "Jira-spec-artifacts". It'll be called something like "FHIR-us-davinci-crd.xml" (with your IG code substituted in for davinci-crd and possibly the realm changed).
Corey Spears (Oct 14 2021 at 22:57):
@Lloyd McKenzie , For new projects, is an xml file with the artifacts generated that can be used as a base? I am not seeing any xml files in my local build that looks like a jira specs file. Is there something I have to do in the configuration to create it?
Sarah Gaunt (Oct 15 2021 at 00:10):
You need to create a listing in the jira spec file in the git repo and then create the file for the new project - instructions here: https://confluence.hl7.org/display/HL7/Configuring+Specification+Feedback
Brian Reinhold (Oct 15 2021 at 09:02):
@Lloyd McKenzie
This is what I see now:
<?xml version="1.0" encoding="UTF-8"?>
<specification gitUrl="https://github.com/HL7/PHD" url="http://hl7.org/fhir/uv/phd" ciUrl="http://build.fhir.org/ig/HL7/PHD" defaultWorkgroup="dev" defaultVersion="0.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../schemas/specification.xsd">
<version code="0.1"/>
<artifactPageExtension value="-definitions"/>
<artifactPageExtension value="-examples"/>
<artifactPageExtension value="-mappings"/>
<artifact name="Device" key="Device" deprecated="true"/>
<artifact name="Observation" key="Observation" deprecated="true"/>
<artifact name="StructureDefinition" key="StructureDefinition" deprecated="true"/>
<page name="(NA)" key="NA"/>
<page name="(many)" key="many"/>
<page name="(profiles)" key="profiles"/>
<page name="languages" key="languages" url="languages" deprecated="true"/>
</specification>
So basically I have to fork this project, update this file, and then make a pull request. I guess it's step two that is the work when I try and follow https://confluence.hl7.org/display/HL7/Configuring+Specification+Feedback provided by Sarah.
Here is what I see in my local home directory: Is it okay to use this?
<?xml version="1.0" encoding="UTF-8"?>
<specification xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ballotUrl="http://hl7.org/fhir/uv/phd/2019May" ciUrl="'http://hl7.org/fhir/uv/phd" defaultVersion="1.0.0" defaultWorkgroup="dev" gitUrl="https://github.com/HL7/PHD" url="http://hl7.org/fhir/uv/phd">
<version code="current" url="'http://hl7.org/fhir/uv/phd"/>
<version code="1.0.0" url="http://hl7.org/fhir/uv/phd"/>
<version code="0.3.0" url="http://hl7.org/fhir/uv/phd/2019May"/>
<version code="0.2.0" deprecated="true" url="http://hl7.org/fhir/uv/phd"/>
<version code="0.1.0" deprecated="true" url="http://hl7.org/fhir/uv/phd"/>
<artifactPageExtension value="-definitions"/>
<artifactPageExtension value="-examples"/>
<artifactPageExtension value="-mappings"/>
<artifact id="CodeSystem/ASN1ToHL7" key="CodeSystem-ASN1ToHL7" name="ASN1ToHL7"/>
<artifact id="ValueSet/ASN1attribute" key="ValueSet-ASN1attribute" name="ASN1attribute"/>
<artifact id="ValueSet/ASN1measurement" key="ValueSet-ASN1measurement" name="ASN1measurement"/>
<artifact id="ValueSet/CodeableConcept11073MDC" key="ValueSet-CodeableConcept11073MDC" name="CodeableConcept11073MDC"/>
<artifact id="CodeSystem/ContinuaDeviceIdentifiers" key="CodeSystem-ContinuaDeviceIdentifiers" name="ContinuaDeviceIdentifiers"/>
<artifact id="CodeSystem/ContinuaHFS" key="CodeSystem-ContinuaHFS" name="ContinuaHFS"/>
<artifact id="CodeSystem/ContinuaPHD" key="CodeSystem-ContinuaPHD" name="ContinuaPHD"/>
<artifact deprecated="true" key="Device" name="Device"/>
<artifact id="Bundle/bundle-continuousnonin" key="Bundle-bundle-continuousnonin" name="Example Bundled upload"/>
<artifact id="Observation/bloodPress-1.0.1" key="Observation-bloodPress-1.0.1" name="Example of Compound measurement"/>
<artifact id="Device/phd-74E8FFFEFF051C00.001C05FFE874" key="Device-phd-74E8FFFEFF051C00.001C05FFE874" name="Example of PHD Device"/>
<artifact id="Observation/stringenum-1234" key="Observation-stringenum-1234" name="Example of String measurement"/>
<artifact id="Observation/bits-1.0.0.40" key="Observation-bits-1.0.0.40" name="Example of a ASN1 BITs measurement"/>
<artifact id="Device/phd-711000FEFF5F49B0.B0495F001071" key="Device-phd-711000FEFF5F49B0.B0495F001071" name="Example of a Blood Pressure PHD"/>
<artifact id="Observation/coin-20181119202022" key="Observation-coin-20181119202022" name="Example of a Coincident Time Stamp"/>
<artifact id="Observation/coin-20181119174911" key="Observation-coin-20181119174911" name="Example of a Coincident Time Stamp"/>
<artifact id="Observation/coin-1234" key="Observation-coin-1234" name="Example of a Coincident Time Stamp referenced by the Glucose Meal Context Observation"/>
<artifact id="Observation/coin-fault20" key="Observation-coin-fault20" name="Example of a Coincident Time Stamp with a Time Fault"/>
<artifact id="Device/phg-ecde3d4e58532d31.000000000000" key="Device-phg-ecde3d4e58532d31.000000000000" name="Example of a Gateway"/>
<artifact id="Device/phd-00601900010E9234.F45EABA80832" key="Device-phd-00601900010E9234.F45EABA80832" name="Example of a Glucose Monitor PHD"/>
<artifact id="Observation/nan-1.0.0.42" key="Observation-nan-1.0.0.42" name="Example of a NaN case"/>
<artifact id="Patient/sisansarahId.1.2.3.4.5.6.7.8.10" key="Patient-sisansarahId.1.2.3.4.5.6.7.8.10" name="Example of a Patient"/>
<artifact id="Bundle/nonin-hdp-1542718631721" key="Bundle-nonin-hdp-1542718631721" name="Example of a first time Bundle upload"/>
<artifact id="Observation/spotnumeric-1.0.0.3" key="Observation-spotnumeric-1.0.0.3" name="Example of a numeric."/>
<artifact id="Observation/rtsa-1234" key="Observation-rtsa-1234" name="Example of an Rtsa."/>
<artifact id="Observation/glucose-1.0.0.4" key="Observation-glucose-1.0.0.4" name="Example of coded enumeration"/>
<artifact id="ValueSet/MDCnotObject" key="ValueSet-MDCnotObject" name="MDCnotObject"/>
<artifact id="CodeSystem/measurement-status" key="CodeSystem-measurement-status" name="Measurement status codes"/>
<artifact deprecated="true" key="Observation" name="Observation"/>
<artifact id="StructureDefinition/PhdBaseObservation" key="StructureDefinition-PhdBaseObservation" name="PhdBaseObservation"/>
<artifact id="StructureDefinition/PhdBitsEnumerationObservation" key="StructureDefinition-PhdBitsEnumerationObservation" name="PhdBitsEnumerationObservation"/>
<artifact id="StructureDefinition/PhdCodedEnumerationObservation" key="StructureDefinition-PhdCodedEnumerationObservation" name="PhdCodedEnumerationObservation"/>
<artifact id="StructureDefinition/PhdCoincidentTimeStampObservation" key="StructureDefinition-PhdCoincidentTimeStampObservation" name="PhdCoincidentTimeStampObservation"/>
<artifact id="StructureDefinition/PhdCompoundNumericObservation" key="StructureDefinition-PhdCompoundNumericObservation" name="PhdCompoundNumericObservation"/>
<artifact id="StructureDefinition/PhdDevice" key="StructureDefinition-PhdDevice" name="PhdDevice"/>
<artifact id="StructureDefinition/PhdNumericObservation" key="StructureDefinition-PhdNumericObservation" name="PhdNumericObservation"/>
<artifact id="StructureDefinition/PhdPatient" key="StructureDefinition-PhdPatient" name="PhdPatient"/>
<artifact id="StructureDefinition/PhdRtsaObservation" key="StructureDefinition-PhdRtsaObservation" name="PhdRtsaObservation"/>
<artifact id="CapabilityStatement/PhdServerCapabilityStatement" key="CapabilityStatement-PhdServerCapabilityStatement" name="PhdServerCapabilityStatement"/>
<artifact id="StructureDefinition/PhdStringEnumerationObservation" key="StructureDefinition-PhdStringEnumerationObservation" name="PhdStringEnumerationObservation"/>
<artifact id="StructureDefinition/PhgDevice" key="StructureDefinition-PhgDevice" name="PhgDevice"/>
<artifact id="ValueSet/Quantity11073MDC" key="ValueSet-Quantity11073MDC" name="Quantity11073MDC"/>
<artifact id="ValueSet/Range11073MDC" key="ValueSet-Range11073MDC" name="Range11073MDC"/>
<artifact id="ValueSet/String11073MDC" key="ValueSet-String11073MDC" name="String11073MDC"/>
<artifact deprecated="true" key="StructureDefinition" name="StructureDefinition"/>
<page key="NA" name="(NA)"/>
<page key="many" name="(many)"/>
<page key="EnumString" name="A measurement that is a human readable string (Enumeration String)"/>
<page key="ASN1BITsCodeSystem" name="ASN1 BITs Code System"/>
<page key="ASN1ToHL7Codes" name="ASN1 BITs Codes"/>
<page key="phgExample" name="Android Gateway example"/>
<page key="artifacts" name="Artifact List"/>
<page key="Audience" name="Audience"/>
<page key="BITsDevSensor" name="BITs measurement; Device-Sensor status"/>
<page key="BaseObservationProfile" name="Base Observation Profile"/>
<page key="bundleExample" name="Bundled upload of Patient, Device, and Observation resources"/>
<page key="CodeableConcepts" name="Codeable Concepts"/>
<page key="glucoseEnum" name="Coded Enumeration"/>
<page key="CoincidentTimeStamp" name="Coincident Time Stamp"/>
<page key="coinFault" name="Coincident Time Stamp with a time fault"/>
<page key="coincidentTime" name="Coincident Time Stamp: PHG best synchronized"/>
<page key="bloodPress" name="Compound Measurement"/>
<page key="ProfileConsumers" name="Consuming the PHD Profile FHIR Resources"/>
<page key="DIMtoFHIRMapping" name="DIM to FHIR Mapping: Basics"/>
<page key="DIMtoFHIRMappingDetails" name="DIM to FHIR Mapping: Details"/>
<page key="DefinitionMetricMsmt" name="Definition of a Metric Measurement"/>
<page key="DeviceIdentifierCodes" name="Device Identifier codes"/>
<page key="phdExample" name="Device example from a Blood Pressure PHD"/>
<page key="downloads" name="Downloads"/>
<page key="GeneralNotestoConsumers" name="General Notes to Consumers of FHIR Data"/>
<page key="GeneratingtheReportedTimeStampIdentifier" name="Generating the PHD Reported Time Stamp Identifier"/>
<page key="ContinuaPersonalAreaNetworkCodes" name="Generating the PHD codes"/>
<page key="GenericModel" name="Generic and Extensible Model"/>
<page key="MderFLOATsandSFLOATs" name="Mder FLOATs and SFLOATs"/>
<page key="MetricAttributesofNoInterest" name="Metric Protocol-Only Attributes"/>
<page key="NumericNaN" name="NaN Example"/>
<page key="Nomenclaturecodes" name="Nomenclature codes"/>
<page key="Non1107320601Devices" name="Non 11073 20601 Devices"/>
<page key="ObtainObservationCode" name="Obtaining the Observation Code"/>
<page key="ObtainUnitCode" name="Obtaining the Unit Code"/>
<page key="Organization" name="Organization"/>
<page key="overview" name="Overview"/>
<page key="BITsEnumerationObservationProfile" name="PHD BITs Coded Enumeration Observation Profile"/>
<page key="CodedEnumerationObservationProfile" name="PHD Coded Enumeration Observation Profile"/>
Well, I guess it was too big to fit the remainder
Lloyd McKenzie (Oct 15 2021 at 13:10):
That sounds like the right process, yes. It seems like you have a lot of pages in your IG. Best practice for a single page to be at least a page worth of printed content - you don't want your readers to have to click through a huge number of pages just to read the IG.
Corey Spears (Oct 17 2021 at 17:06):
@Sarah Gaunt , Thanks. I see:
The initial version can be created from scratch (ignoring artifacts and pages other than 'generic' pages such as "(N/A)") or by copying from the Jira Spec file for an existing IG.
I heard that is a way to do it. I wanted to be sure it was the official way to trigger it.
Sarah Gaunt (Oct 18 2021 at 22:00):
I hate the jira spec file process with every single fibre of my being!
Grahame Grieve (Oct 18 2021 at 22:02):
we need to come up with something better. Any ideas?
Sarah Gaunt (Oct 18 2021 at 22:43):
Well, it would be great if we could just use file generated by the build process - but I've discussed that with Lloyd and it's a no-go. Because of deprecated profiles etc., I think. I'm guessing that if @Lloyd McKenzie can't think of a way to automate it, then I am probably not going to be able to come up with anything.
Saul Kravitz (Oct 18 2021 at 22:53):
Jira spec file is definitely a character-building exercise.
Lloyd McKenzie (Oct 19 2021 at 01:39):
Most of those building IGs are characters already...
Lloyd McKenzie (Oct 19 2021 at 01:39):
There actually is a plan to change the process, though whether it'll be perceived as "better", I don't know.
Lloyd McKenzie (Oct 19 2021 at 01:43):
The plan is to move Specification Definitions into a Jira project so that specs and their versions can be actively managed (and have timeouts based on last publication date that trigger notification emails and TSC badgering, etc.). As part of this, instead of needing to "merge" JiraSpecArtifact files, you'll be able to edit the list of artifacts directly in Jira as a table. You'll also be able to 'import' a generated list of proposed changes suggested by the IG publication process. However, you'll still be looking at reviewing that proposed set of changes - which will be in some sort of computable syntax (my default is XML, though I'm open to others) - and editing it to reflect what you want.
Lloyd McKenzie (Oct 19 2021 at 01:44):
Another thing I would like to do is to just group all example files under a simple "(examples)" page and no longer manage independent artifact rows for all examples. That seems to be where some of the greatest merging pain is coming from, and we could care less about tracking issues across versions because they're always informative and can't have maturity.
Lloyd McKenzie (Oct 19 2021 at 01:44):
Timeline for all of this is "spring-ish".
Lloyd McKenzie (Oct 19 2021 at 01:45):
Other ideas for reducing the pain are welcome...
Sarah Gaunt (Oct 19 2021 at 02:14):
I _think_ I like it better. I presume this means there won't be a wait time after changes are made like there is now (BTW, i totally appreciate how you almost always manage to do the merge in a timely manner even with our differing TZs!).
Jean Duteau (Oct 19 2021 at 03:06):
why can't we use the file generated by the build process? that's all I ever use. When my guide is at a state where I'm ready to ballot or publish, that's when I take the generate file and push it to the Jira Spec Artifacts project.
Sarah Gaunt (Oct 19 2021 at 03:07):
Me too, but @Lloyd McKenzie has a reason (that seems to make sense when he tells me, but that I can't actually describe after the fact!)...
Jean Duteau (Oct 19 2021 at 03:09):
yeah, 21 years of working with Lloyd and that's my take on his reasons too - they make sense at the time but when I try to tell someone else...
Corey Spears (Oct 19 2021 at 03:27):
One issue with that is that it would create additional constraints that do not already exist on IGs. Specifically, artifacts can't have the same name even though they are a different type of artifact. One specific example of this is the CARIN BB IG that names ValueSets and CodeSets the same thing. This causes a naming collision in the JIRA artifact names that have to be manually differentiated. One can dispute the use of this practice, but it is a small example of potential issues with auto generated files.
Sarah Gaunt (Oct 19 2021 at 03:32):
In those cases, the auto-generated file could be manually edited. But if most people are just using the auto-generated file anyway, it sure would make things easier...
Lloyd McKenzie (Oct 19 2021 at 04:19):
The IG-publisher generated file has no clue when you rename something. It sees that as a delete and an add. If you process it that way, then none of the history of tracker items against the 'old' name carries forward to the 'new' item. The only way to address it is for a human being to look at the content. Also, sometimes you don't want all of the artifacts listed. For example, in the core spec, there are pages for every single value set and code system - but we don't define artifacts for those - instead feedback is tracked against the associated resources or the 'terminologies' page. That's a better experience for users dealing with the dropdowns and reflects the granularity at which committees manage maturity. (Terminology is driven by resource maturity.) Unfortunately, most work groups haven't really bothered with that capability as part of uploading their files. I'm not sure if the new process will make that better.
Jean Duteau (Oct 19 2021 at 05:37):
i just make sure that I don't have the same name for things. makes it confusing in real life as well as in Jira :)
Lloyd McKenzie (Oct 19 2021 at 13:19):
Same name is certainly something you need to avoid. But it's the "renaming" of artifacts and pages that creates issues.
Josh Mandel (Oct 19 2021 at 14:02):
Would it be possible for the automatic generation process to the better informed by the git history in a FHIR ig? Like if a file was git mv'd? (Please ignore this if it's an irrelevant suggestion; I don't really understand what we're talking about here :-))
Lloyd McKenzie (Oct 19 2021 at 15:11):
First, I figure that only about half of our Git committers will use Git mv - the other half will likely do a delete + add. Second, is there a way to get access to Git history in a computable form?
Josh Mandel (Oct 19 2021 at 15:57):
I don't know -- I mean, a rough cut is
$ git log --follow -p input/pages/ | grep "rename from" -A 1
rename from input/pages/index.md
rename to input/pages/app-launch.md
--
rename from input/pages/overview.md
rename to input/pages/index.html
But you're probably want a script to interact with git internals to do this properly.
Last updated: Apr 12 2022 at 19:14 UTC
