Formalizing process for ODK XForms spec changes

Development
,
1

@issa brought up in Disable choosing an image, video or audio the desire for a more formal process for adding on to the ODK XForms specification. I agree that this would be good to do. @Alex_Dorey, Alex Anderson from Medic Mobile and @martijnr started a brief conversation in Slack. Some of the things we should establish are:

  • where conversations should happen (here vs. GitHub)
  • what standard of approval is needed for the different kinds of changes that may be proposed
  • what people/organizations should be involved

Recently, the majority of changes to the spec have been to reflect conversations that came to conclusion but were never formally added (e.g. orx:auto-send and orx:auto-delete) or to introduce missing functionality defined by the XForms 1.0 or XPath specifications (e.g. contains, starts-with, ends-with). The former generally already had pretty significant conversations associated to them and the latter I don't think need as much discussion.

We've also had some high-level discussions on GitHub:

I think there were a lot of valuable conclusions drawn in those conversations and that it would be great to summarize, codify them and include them in the specification. It might be even more valuable if someone not directly involved in those conversations could take the lead on that. This would help us verify that the ideas were clear and coherent.

Here is a strawman approval process:

  • All discussion about changes to the ODK XForms spec must happen on a new Development/ODK-XForms forum category so people can subscribe to it specifically
  • All proposals must use a particular template so things like benefits and naming options are carefully considered
  • Follow the voting rules outlined in governance
  • Additionally, at least N representatives of organizations that implement the spec must agree on the change (vote +0 or +1) (I will throw out 3 as a value for N)
  • GitHub issues are filed once the change is agreed on and just needs to be written up formally

Again, this is just a strawman. I'd also be fine with all of this happening in GitHub issues as it has been recently since it's very clearly developer-centric except for appearances which form creators do interact with and I think should be discussed on the forum. I'd be fine with not requiring specifically that different organizations be involved.

@martijnr @Alex_Dorey @abbyad (and by extension Alex but I can't find him!) @Matt_Berg @yanokwa @Tino_Kreutzer @tomsmyth @daveycrockett @Xiphware are people I can think of who would be interested in this discussion off the top of my head!

2 Likes
2

I just had another thought from a conversation that's happening on the XLSForm side here. I think we should propose changes to the ODK XForms and XLSForm specs together rather than tackling them separately. I think considering them together may have been a convention at some point but recently it looks like they've been approached separately.

On the ODK XForms side, we think about the most expressive and consistent way to make additions. On the XLSForm side, we think about the most human-friendly way to do the same thing. I think that considering those different angles at the same time may help us get better solutions (the recent example with print hints/expanded hints in ODK XForms and XLSForm is a good example, I think). Plus, it means we can stay in the same brain space and solve a particular problem once rather than having to come back to it at different times.

2 Likes
3

@ln thanks for proposing this. This seems very sensible to me. I think the combination of XLSForm and XForm is going to create some confusion (and maybe loss of interest) for participants, but I think it's worth trying as it would catch everything regardless of whether it ends up being "just" a new appearance or a new XForms type or something else. Those outcomes are not always obvious in the beginning.

Requiring at least 3 different organizations to vote, seems great to me.

1 Like
4

If the XLSForm / XForm combination doesn't seem like a good idea, we don't have to do it. I'm personally getting confused moving back and forth between different feature types and spec types so I believe it would help me think more clearly. I can imagine others may approach them in a different way or perhaps may only care about one spec but not the other.

Another option is that we could say all spec change proposals get made in parallel on the two different repos and perhaps appearance changes always go to the pyxform repo only. This is roughly what has been happening recently although often the change on one side gets accepted before the other conversation completes.

1 Like
5

@ln The idea of consolidating spec changes into one place would definitely make life easier, and the proposed process makes sense. The voting requirement should not be a limitation, as it looks past spec changes have been supported by at least 3 representatives anyway.

2 Likes