Stream: committers
Topic: Maintaining "Jira Spec Artifacts" for IGs
Josh Mandel (Dec 18 2020 at 23:08):
Hi Committers! In our FHIR Management Group calls, we've been discussing some of the overhead and difficult of getting an IG ready for ballot (and harder still: publication). One area where we've created some overhead for ourselves is the collection of data to populate structured fields in Jira like:
i.e., there are detailed fields for every version, artifact, and page in every IG, which must never be removed (one can only add to the list). All of this is backed by XML files in a separate repo from the IG (see this example for US Core), which means creating pull requests, waiting for an administrator to merge, failed builds, etc.
My question: how valuable are these fields in Jira? How often do you filter/query off of them, and does this work better than, say, free-text search? I'm trying to understand whether the "juice is worth the squeeze" on IG authors, to keep all these detailed fields populated in the Jira plugin/templates that support issue creation.
Eric Haas (Dec 18 2020 at 23:53):
My feeling is all you really need is the "Related URL" and that should be required by committers with an option for various or general comment. I rarely use the other fields to locate an issue I only enter them because I have to. I always stick the Jira issues warning in the ignore warnings file because it shows up despite me reconciling and pushing it.
Josh Mandel (Dec 19 2020 at 16:42):
(For "required URL", is it important for this field to be validated @Eric Haas or is the current freeform structure okay?)
Eric Haas (Dec 19 2020 at 17:20):
I think it would helpful to have either a url or a checkbox for various or general comment (such as"this is an awsome IG!!!") and require one or the other.
Josh Mandel (Dec 19 2020 at 18:16):
I'm not sure I'm following --in the Jira submission form, the URL identifies what you're commenting about, which is distinct from where/how you share the content of your comments.
Lloyd McKenzie (Dec 19 2020 at 19:35):
Right now, the URL isn't free-form. It must be a valid URL and must be rooted in the CI-build or official publication URL for that IG. You're also limited to having only one. Starting soon, if you specify a URL.
Lloyd McKenzie (Dec 19 2020 at 19:36):
I think that Eric is saying that if you're not going to provide a URL, you need to set a flag that says "this isn't a page-specific comment".
Lloyd McKenzie (Dec 19 2020 at 19:37):
As a side note, be aware that Jira balloting is also going to be used for specifications that aren't published as websites, though the number of those will be relatively small once CDA and v2 are both using the FHIR publication mechanism. EHR functional models, any PDFs we put out, etc. won't have URLs.
Josh Mandel (Dec 19 2020 at 21:55):
Re: PDF publications etc -- Sure, but let's leave that outside the scope of this discussion
Lloyd McKenzie (Dec 19 2020 at 22:05):
Any decision we make on metadata needs to work for all of our publication types. (i.e. If we get rid of artifacts/pages and make URLs mandatory, we'll have to allow URLs to be omitted for PDFs and accept not having any metadata at all other than the free-text "section" element. (Unless we introduce something new.)
One last consideration to be aware of - page/artifact can remain consistent even when elements are renamed. For example, comments submitted against the "Conformance" resource are now associated with the "Capability Statement" page. If we only capture URL, we'll lose that ability.
Josh Mandel (Dec 20 2020 at 04:47):
The purpose of this discussion wasn't to make any decisions, @Lloyd McKenzie . (Of course we aren't constrained to a one size fits all solution, and it's a fallacy to assume that edge cases should dictate core process.) You asked me to start a discussion about how much utility IG authors get from the set of structured data entry fields in Jira; what they're using them for; and whether this value is worth the pain of maintaining and trying to synchronize every piece of content in every version of every IG with an append-only XML file in a distinct repository that the IG authors can't directly commit to.
Grahame Grieve (Dec 20 2020 at 19:57):
in the core spec, I use the resource type a lot. I don't use other fields as filters, as they tend to be too hit and miss. I do use the page a lot, when I'm trying to figure out what they meant since things have been moved.
IGs are messier, since it's not so simple to group
Melva Peters (Dec 21 2020 at 14:57):
For core, I also use the resource type a lot in searching for issues that have previously been dealt with for a resource or to group issues together so that we can ensure that we are dealing with "like" issues when making decisions.
David Pyke (Dec 21 2020 at 15:19):
For IG comments, being able to link to a specific page and/or profile, etc. is useful, and speeds up reconciliation. If a combination of page and line numbers were possible that would make comments on prose even better.
Lloyd McKenzie (Dec 21 2020 at 16:09):
page + line number for PDF only? (Not really relevant for web-based, I think...)
David Pyke (Dec 21 2020 at 16:17):
THat might work. Line number is reasonably impossible due to screen sizes but I have a dream
Brett Marquard (Dec 22 2020 at 17:58):
Related URL is all I reference....I can see how Resource would be useful for FHIR core.
Last updated: Apr 12 2022 at 19:14 UTC
