Stream: implementers
Topic: typos
Jens Villadsen (Aug 20 2019 at 14:56):
Why is it necessary to submit a task in order to have a typo fixed in the spec? It seems a bit counterproductive
Jens Villadsen (Aug 20 2019 at 14:57):
could the spec be put on a git repo and the people could make PR's in an instant for such small details
Michel Rutten (Aug 20 2019 at 15:01):
You could submit a task to improve procedure... ;p
Jens Villadsen (Aug 20 2019 at 18:37):
thats almost funny ...
Jens Villadsen (Aug 20 2019 at 18:38):
git is probably known as one of the most successful collaboration tools out there ... why not join in on that, making it a lot easier to add contributions?
Jens Villadsen (Aug 20 2019 at 18:46):
and ... Github and friends makes it pretty easy to make contributions while keeping transparency
Chris Moesel (Aug 20 2019 at 19:03):
I'm confused. Are you talking about something other than the spec that is here: https://github.com/hl7/fhir ?
Bryn Rhodes (Aug 20 2019 at 19:04):
The spec is on github: https://github.com/HL7/fhir and we do use PRs to make actual changes to it. But because the specification is an HL7 standard, changes made have to be approved following the standards required by HL7, so for that process we use gforge.
Jens Villadsen (Aug 21 2019 at 09:16):
@Bryn Rhodes so you are saying that if I actually did a PR on github, it would not be processed unless I created a gforge task, right?
Lloyd McKenzie (Aug 21 2019 at 12:09):
Someone would have to create it - and we certainly prefer it be created by the person who's asking for the change/correction
Jens Villadsen (Aug 21 2019 at 13:37):
So ... a git webhook that automatically created a gforge task referring the PR could probably do the trick, right? (@Lloyd McKenzie )
Jens Villadsen (Aug 21 2019 at 13:55):
Does this API reflect the capabilities of the HL7 Gforge? https://next.gforge.com/apidoc
Lloyd McKenzie (Aug 21 2019 at 14:21):
Two challenges:
- extracting the mandatory gForge metadata from the Git PR (e.g. what page or resource does it apply to)
- converting between Github user id and gForge registered user
I'm not sure we're on the current version of gForge. Also, I hope for us to be off gForge in the next 6-8 weeks, so I'm not sure there's a lot of value in doing that. Playing around with Jira is probably a better time investment (though the same issues as above will still be there).
Josh Mandel (Aug 21 2019 at 14:27):
Developing a GH PR -> Jira Request interface would be a great project though, for someone who wanted to "bridge" from "convenient developer experience" to "formal HL7 process requirements." (An even better project would be getting HL7 to "deem" certain GH PRs as an acceptable place for us to review/approve issues.
Jens Villadsen (Aug 21 2019 at 14:27):
1) Default to use the current defaults when creating a new tracker item
2) create a new user on Gforge that matches you github creds.
I as a developer am lazy - yet I like to contribute with my findings, meaning: I would like to do the PRs to the existing material, using the usual dev tools.
Josh Mandel (Aug 21 2019 at 14:29):
Would definitely encourage you to experiment with what you can connect/integrate!
Jens Villadsen (Aug 21 2019 at 14:29):
Developing a GH PR -> Jira Request interface would be a great project though, for someone who wanted to "bridge" from "convenient developer experience" to "formal HL7 process requirements." (An even better project would be getting HL7 to "deem" certain GH PRs as an acceptable place for us to review/approve issues.
The funny thing is here that making the process cumbersome by not using eg. GH, means that valuable input never reach the standard due to laziness.
Josh Mandel (Aug 21 2019 at 14:29):
Agreed 100%.
Jens Villadsen (Aug 21 2019 at 14:30):
Would definitely encourage you to experiment with what you can connect/integrate!
its 2019 ... there's a tesla circling around the planet ... it shouldn't be impossible to do
Lloyd McKenzie (Aug 21 2019 at 14:30):
1. There are no defaults. And gForge doesn't enforce HL7's rules that say "you must pick at least one page or resource" - instead that's done by a manual report after the fact and badgering submitters or fixing it for them (because gForge sucks). I don't want an automated process that increases that workload
Josh Mandel (Aug 21 2019 at 14:30):
From personal experience though: trying to automate GForge tasks is a huge pain. https://github.com/jmandel/csv-to-fhir-tracker/blob/master/drive-gforge.py has what I put together for loading ballots...
Lloyd McKenzie (Aug 21 2019 at 14:30):
2. Not kosher. If a user already has a gForge id, that's the id the item needs to be tied to.
Lloyd McKenzie (Aug 21 2019 at 14:31):
Otherwise, filtering for "my" items, permissions about editing, etc. get messed up (and will be worse in Jira)
Josh Mandel (Aug 21 2019 at 14:31):
Lloyd, I think we could look a bit more expansively at what the process allows. Let's talk through this a bit in FMG if we have time today. At least from the brainstorming perspective.
Jens Villadsen (Aug 21 2019 at 14:31):
2. Not kosher. If a user already has a gForge id, that's the id the item needs to be tied to.
laziness would probably make me create a new gforge id
Jens Villadsen (Aug 21 2019 at 14:32):
My two cents are: make it dev friendly to submit content. That is all
Jens Villadsen (Aug 21 2019 at 14:32):
Dixi
Lloyd McKenzie (Aug 21 2019 at 14:33):
I'm happy for us to explore a process to make this work with Jira. I'm not much interested in trying to make it work now with gForge.
@Jens Villadsen I'm not sure that pull requests against HL7's source (which doesn't necessarily have clear logical correspondence with published content) is super developer friendly. I'm not opposed to enabling that (in Jira) for those that want to, but I certainly expect the majority of feedback to come without a pull request.
Grahame Grieve (Aug 21 2019 at 19:40):
actually, I'll process pure typos as GH PRs without needing gforge tasks. But only pure typos . Otherwise, please join the refrain: we hate gForge. But honestly, I don't see how Jira will really make a difference here; you aren't going to have the metadata about the work from a github PR to feed into the HL7 process
Josh Mandel (Aug 21 2019 at 20:55):
Great -- just confirmed Grahame's process on our weekly #fmg (members only) call. So if you have a simple typo fix, just go ahead and create a PR. (But keep in mind that many things that look like simple typos can be deeper / more complex, originating from generated code rather than hand-authored content.)
Grahame Grieve (Aug 21 2019 at 20:58):
also, we get lots of 'typos' that are not typos at all; they are readers misunderstanding what is being said
Lloyd McKenzie (Aug 21 2019 at 20:59):
It's not clear that for normative elements, we can do this. I think ANSI rules require us to have clear traceability for all changes - and gForge/Jira is our traceability mechanism. If we're going to allow an alternative process, we're going to need to get it cleared by both the TSC and Karen.
Lloyd McKenzie (Aug 21 2019 at 21:00):
For STU stuff it's not a big deal. (And for draft stuff, it's always been "fix at will" - typo or not.)
Lloyd McKenzie (Aug 21 2019 at 21:01):
(And if we're going to have different rules for content with different statuses, we'll need to ensure the process includes evaluation of the status before changes are applied - and figure out whether that added complexity is going to be confusing to those who want to use the process - particularly as more content becomes normative.)
Jens Villadsen (Aug 21 2019 at 21:11):
It's not clear that for normative elements, we can do this. I think ANSI rules require us to have clear traceability for all changes - and gForge/Jira is our traceability mechanism. If we're going to allow an alternative process, we're going to need to get it cleared by both the TSC and Karen.
Who defines what constitutes the accepted traceability mechanism here? The ones bringing the content of the standard or the curators of the standard?
Lloyd McKenzie (Aug 21 2019 at 21:12):
HL7 - the organization that is the custodian of the standard and is accountable to ANSI for the process.
Jens Villadsen (Aug 21 2019 at 21:13):
And they like to keep their typo's regardless of how easy it ought to be to fix it?
Lloyd McKenzie (Aug 21 2019 at 21:15):
They like to ensure that the process to make changes adhere's to what they've agreed with ANSI they will follow and meets ANSI's requirements.
Lloyd McKenzie (Aug 21 2019 at 21:15):
And yes, they'd rather have typos than fall outside of ANSI's rules
Jens Villadsen (Aug 21 2019 at 21:15):
How would a PR fall outside the rules?
Jens Villadsen (Aug 21 2019 at 21:16):
Its fully traceable
Jens Villadsen (Aug 21 2019 at 21:16):
It requires a distinct set of people to accept it
Lloyd McKenzie (Aug 21 2019 at 21:16):
It's a question of how it's traceable, who approves it, how it manifests to the "approval pool", etc.
Jens Villadsen (Aug 21 2019 at 21:17):
thats seems possible in PR's
Jean Duteau (Aug 21 2019 at 21:17):
@Jens Villadsen You should look at HL7's requirements and see if your proposal meets the traceability rules. tl;dr - it might, but it needs to be clearly documented so that HL7 can answer any questions that are asked when ANSI audits us to ensure openness and traceability.
Lloyd McKenzie (Aug 21 2019 at 21:17):
That's not to say we can't find a way to make PRs work, but it's not as simple as us just saying "let's do it".
Jean Duteau (Aug 21 2019 at 21:18):
http://www.hl7.org/documentcenter/public/procedures/HL7_Essential_Requirements.pdf
Jens Villadsen (Aug 21 2019 at 21:18):
I find it hard to believe that I'm the first one to suggest this
Lloyd McKenzie (Aug 21 2019 at 21:19):
And if we decide to have PRs to normative content (which requires strict traceability), without also capturing information in gForge Jira, there's administrative complexities about managing our documentation of changes and approvals. We'd have to balance the trade-offs of that with the benefit of accepting PRs
Jens Villadsen (Aug 21 2019 at 21:20):
And if we decide to have PRs to normative content (which requires strict traceability), without also capturing information in gForge Jira, there's administrative complexities about managing our documentation of changes and approvals. We'd have to balance the trade-offs of that with the benefit of accepting PRs
you don't believe you have strict traceability in git?
Lloyd McKenzie (Aug 21 2019 at 21:20):
PRs work best when the developer is working with the content that needs to be fixed. In this case, what the developer sees is HTML, generated schemas, generated code, etc. There can be a long (and complicated) walk from there to the source. So it's not a path we would expect to be tread by many.
Jens Villadsen (Aug 21 2019 at 21:21):
PRs work best when the developer is working with the content that needs to be fixed. In this case, what the developer sees is HTML, generated schemas, generated code, etc. There can be a long (and complicated) walk from there to the source. So it's not a path we would expect to be tread by many.
thats another problem ... but essentially a detail
Lloyd McKenzie (Aug 21 2019 at 21:23):
Traceability means "what reports do the ANSI folks look at to see what content was changed in the published specification, why, and by whom and with what oversight". Pull requests don't directly answer those questions because they aren't documented in terms of the published spec, they're documented in terms of the source. They don't capture oversight in the way HL7 typically does either (i.e. what WG voted to approve).
Lloyd McKenzie (Aug 21 2019 at 21:23):
Again, we're not saying "no". We're saying "it's not as straight-forward is you might hope" :)
Jens Villadsen (Aug 21 2019 at 21:24):
git blame ...
Lloyd McKenzie (Aug 21 2019 at 21:25):
Git blame is a user thing - not an "organization" thing
Lloyd McKenzie (Aug 21 2019 at 21:25):
I might approve a pull request - but on behalf of which work group did I do that?
Jens Villadsen (Aug 21 2019 at 21:25):
users makes the standard
Lloyd McKenzie (Aug 21 2019 at 21:26):
Not in HL7. Work groups make the standard. Work groups are the basis of authority for making changes.
Jens Villadsen (Aug 21 2019 at 21:26):
work groups consists of users
Lloyd McKenzie (Aug 21 2019 at 21:26):
Individuals are responsible for applying the will of the work group.
Lloyd McKenzie (Aug 21 2019 at 21:26):
The same user might be part of multiple work groups.
Jens Villadsen (Aug 21 2019 at 21:27):
good for him - then make a user that reflects that group
Jens Villadsen (Aug 21 2019 at 21:28):
this is not entirely fruitful ...
Grahame Grieve (Aug 21 2019 at 21:30):
ANSI rules around normative content are - rightfully - strict.
- you have to have an open transparent documented process
- you have to do what you say, and say what you do
- you have to be able to prove that to us
That seems pretty reasonable to me. So, no, it's not a simple open source process where you can just do things. I haven't approved a typo in normative content before this.
Lloyd McKenzie (Aug 21 2019 at 21:31):
And who gets that user id - when multiple users can work on behalf of the same group.
I agree. If you haven't been immersed in HL7 process for a decade or two, you won't necessarily understand our concerns. At this point, just accept that your desire to submit fixes directly as PRs has been heard. It'll be an agenda item for the relevant governance groups to figure out if/how to make it work within the processes HL7 needs to adhere to. When we have answers to share, we'll share them here.
Jens Villadsen (Aug 21 2019 at 21:37):
I never compared this to some 'simple open source process'. I would rather compare it to a highly complex software setup containing loads of 'here be dragons'. And as such, I would imagine that any changes would be tested, reviewed and confirmed in a firmly controlled CD/CI environment with total traceability.
Grahame Grieve (Aug 21 2019 at 21:38):
indeed. that's the PR approval process. But the question in effect becomes: who needs to do the work for traceability - the hopelessly overloaded approvers, or the not-so-interested submitters?
Jens Villadsen (Aug 21 2019 at 21:39):
Such setups however do not run in twenty years by itself. Either the project dies or the environment gets upgraded and tweaked continuously to reflect new needs and processes.
Jens Villadsen (Aug 21 2019 at 21:41):
indeed. that's the PR approval process. But the question in effect becomes: who needs to do the work for traceability - the hopelessly overloaded approvers, or the not-so-interested submitters?
traceability in terms of ... ? I seem to have another understanding of that term than you I think.
Grahame Grieve (Aug 21 2019 at 21:44):
tracability in terms of documented HL7 process
Grahame Grieve (Aug 21 2019 at 21:45):
which includes more metadata than just what a github PR collects
Jens Villadsen (Aug 21 2019 at 21:46):
I imagine there's a reason for that extra metadata requirement, or else the process could be changed, right?
Lloyd McKenzie (Aug 21 2019 at 21:48):
Yes - ANSI needs to know that the whole stakeholder community has had appropriate opportunity to review and approve the content published - and that includes fixes to typos. There are variations in expectation depending on the type of change, but there still needs to be review by appropriate groups - and documentation of what groups reviewed and when.
Lloyd McKenzie (Aug 21 2019 at 21:49):
It's not enough to just know who asked for the change and who applied it.
Jens Villadsen (Aug 21 2019 at 21:51):
It must be an ANSI thing. ISO accepts corrections of typos if im not mistaken without a lot of fuzz
Jens Villadsen (Aug 21 2019 at 21:59):
PRs for typos could be made as eg. a corrigendum
Jens Villadsen (Aug 21 2019 at 21:59):
can't say if that changes much in the proces
Grahame Grieve (Aug 21 2019 at 22:19):
How does ISO accept typo reports?
Jens Villadsen (Aug 22 2019 at 06:58):
How does ISO accept typo reports?
It's something that I recall I've seen, but in essence its probably the same process as with HL7/ANSI, that the typo corrections are handed over to a working group and so on. I can reach out to ISO, if I should dig deeper into this.
Grahame Grieve (Aug 22 2019 at 13:20):
sure you'll find it's not too different to our process - it's not a PR for sure
Abbie Watson (Aug 25 2019 at 01:33):
Zapier has quite a few zaps for integrating GitHub and JIRA. $0.02
https://zapier.com/apps/github/integrations/jira
Now, if only there were a Zapier like service/product for FHIR....
Last updated: Apr 12 2022 at 19:14 UTC
