Re: UCR workflow

Hi All,

With respect to the UCR workflow, IMO it will be more complicated to 
keep updating the information on use cases in two different places 
(github and wiki).

According to the Github workflow described by Simon, potentially only 
the editors will modify the respec documents (unless someone else sends 
a PR with modifications). The rest of the comments can be done through 
issues.

If we use github from now on, it means that new use cases can be added 
as issues in the tracker and then the changes to the document (done by 
the UCR editors) can refer to the specific issues, allowing to track all 
the changes made and why they were performed.

Just some comments on the options that Karen listed (#1 = wiki, #2 = 
github):

 >For #1, options seem to be:
 > - mark all use cases in the github document with their status, or
 > - leave use cases in the wiki until they are accepted, then add them to
 >the github document

This is ok if the UCR editors are happy with this, but it means that 
they will need to link each commit with the wiki manually (if we want to 
have the full audit trail that Karen mentioned).

Otherwise, as above, if the use cases are added as github issues, 
discussions about the use case can happen in github and the 
modifications in the document can refer to the issue in the commits.

 >For #2, options are:
 > - Add new use cases to the Wiki document, and inform the chairs so they
 >can schedule them on a conference call

 > - Add new uses cases directly to the github document, and inform the
 >chairs so they can schedule them on a conference call

As before, if people don't want to modify the document, it would be 
enough for them to include an issue in the tracker.

One question arises: if the document is modified and the changes sent in 
a pull request, how do we know when the whole group agreement is needed 
(and thus, it needs to be discussed in call) vs an editor can review the 
changes and add the modifications?

 > - Add new uses cases as comments on the github document, and editors
 >will add them

Karen, what did you mean by adding the use cases as comments here?

Thanks,

Alejandra


On 04/08/2017 22:58, Rob Atkinson wrote:
> I agree - editing the respec document is not for everyone.
>
> I suggest tagging the wiki - maybe we can make sure the tags are up to 
> date and leave it as the place where new use cases are proposed and 
> discussed. Can we have a volunteer to audit and update the tags - and 
> put a process explanation into the wiki - may be required in order to 
> manage the discussion process.  When these are done I will look at the 
> respec document and make sure out-of-scope Use Cases are pruned out.
>
> Jaroslav is away, but pulled all the Use cases across and did a lot of 
> scripting, and Ixchel and I have started editing requirements - which 
> is where all the analytical process happens to deduplicate and 
> generalised, and we'll need help checking we have got as minimal set, 
> correctly cross references to original use cases.
>
> Rob
>
> On Sat, 5 Aug 2017 at 05:24 Karen Coyle <kcoyle@kcoyle.net 
> <mailto:kcoyle@kcoyle.net>> wrote:
>
>     There is a somewhat cryptic item on Monday's agenda: "UCR entries
>     workflow question" that we thought might benefit from a short
>     explanation in email.
>
>     At the moment we have the draft use case space on the wiki. We
>     also now
>     have a draft UCR document in github that will become our first public
>     working draft. We informally decided at the last meeting that any
>     updates to existing use cases should be made in the github version.
>
>     Unfortunately, that doesn't cover the entirety of the workflow
>     question,
>     so here is a fuller description of that.
>
>     1. The current UCR document in Github contains all use cases that have
>     been submitted. It does not differentiate between those that have been
>     accepted by the group by a vote and those that have not. This is
>     making
>     it difficult to line up as-yet-un-voted use cases for the weekly
>     meetings. (Also note that there are use cases that we reject as
>     out-of-scope.)
>
>     2. We have not decided where new use cases will be entered: the
>     wiki or
>     github?
>
>     For #1, options seem to be:
>      - mark all use cases in the github document with their status, or
>      - leave use cases in the wiki until they are accepted, then add
>     them to
>     the github document
>
>     For #2, options are:
>      - Add new use cases to the Wiki document, and inform the chairs
>     so they
>     can schedule them on a conference call
>      - Add new uses cases directly to the github document, and inform the
>     chairs so they can schedule them on a conference call
>      - Add new uses cases as comments on the github document, and editors
>     will add them
>
>     Some things we need to keep in mind:
>      - We want a good audit trail of what use cases we have
>     considered, even
>     if they are not accepted as in scope by the group
>      - Not everyone is comfortable using github, much less editing a
>     Respec
>     document
>
>     There are probably other issues that we haven't identified here. We'd
>     like to make this a SHORT item on the Monday call, so if you have a
>     preferred solution please offer it to the group via this maillist
>     so we
>     can focus on a small number of solutions.
>
>     kc for the chairs
>     --
>     Karen Coyle
>     kcoyle@kcoyle.net <mailto:kcoyle@kcoyle.net> http://kcoyle.net
>     m: 1-510-435-8234 (Signal)
>     skype: kcoylenet/+1-510-984-3600 <tel:+1%20510-984-3600>
>