Subject: [GNAP] GNAP Editors' Use of GitHub Issues

From: Aaron Parecki <[email-masked]>
Date: Wed, 25 Nov 2020 08:36:37 -0800

The editors met yesterday to discuss the issues that were pulled out of the
previous draft text and document a process for how to resolve these and
future issues. We would like to explain how we plan on using labels on
GitHub issues to keep track of discussions and keep things moving.

When there are substantive issues or pull requests, the editors will avoid
merging or closing those outright, and instead mark them as "pending", so
that these can be brought to the attention of the larger group. If no
additional discussion happens on these, the merge or close action will be
taken in 7 days. Note for this first round we are setting the deadline for
the issues below as Dec 11th due to the US holiday and the fact that this
is the first time using this process.

"Pending Merge"
When specific text is proposed in a PR (by anyone, not limited to the
editors), and the editors believe this text reflects the consensus of the
working group, this marks that the PR will be merged in 7 days unless there
is a clear alternative proposal accepted by the working group.

"Pending Close"
When the editors believe an issue no longer needs discussion, we'll mark it
"Pending Close". The issue will be closed in 7 days unless someone brings
new information to the discussion. This tag is not applied to issues that
will be closed by a specific pull request.

There are two additional labels we will use to flag issues to the group.

"Needs Text"
The editors suggest this issue needs additional text in the spec to clarify
why this section is needed and under what circumstances. Without a concrete
proposal of text to be included in the spec, this section will be removed
in a future update.

"Postponed"
This issue can be reconsidered in the future with a more concrete
discussion but is not targeted for immediate concrete changes to the spec
text. When used on its own, this label does not indicate that an issue is
targeted to be closed. An issue may also be marked "Pending Close", and
this is used so that we can distinguish closed issues between discussions
that have concluded or things that we may want to revisit in the future.
Remember that closed issues are not deleted and their contents are still
findable and readable, and that new issues can reference closed issues.

With these labels in mind, here are the list of issues and their statuses
we were able to discuss on our last editor's call. The action on these
pending issues will be taken on Dec 11th to give the group enough time to
review this list. For this first round, many of the issues are marked
"Pending Close" as we're looking for low hanging fruit to prune the list of
issues down. In the future, you can expect to see more "Pending Merge"
issues as we're bringing proposed text to review by the WG.

Postponed:

* Generic claim extension mechanism
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/131

Pending Merge:

* Make access token mandatory for continuation API calls
** https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/129

Postponed and Pending Close:

* Fetchable Keys
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/47
* Including OpenID Connect Claims
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/64
* Application communication with back-end
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/82
* Additional post-interaction protocols
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/83

Pending Close:

* HTTP PUT vs POST for rotating access tokens
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/100
* Use of hash with unique callback URL
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/84
* Interaction considerations
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/81
* Expanding dynamic reference handles
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/76
* Post interaction callback nonce
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/73
* Unique callback URIs
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/55
* Instance identifier
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/46
* Requesting resources by reference
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/36
* Mapping resource references
** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/35

---
Aaron Parecki
https://aaronparecki.com

---

From: Yaron Sheffer <[email-masked]>
Date: Wed, 25 Nov 2020 20:27:40 +0200

Commenting on the proposed process (chair hat off):

I think “postponed” issues should not be closed. Once something is closed, we should be reasonably confident that it is resolved for good. People rarely search through closed issues.

Moreover, IMO the label “postponed” is not actionable. Instead, I suggest to mark such issues with future milestones, e.g. “IETF110”, meaning that at this time we will review the issue. Otherwise, the “postponed” issues will probably suffer the destiny of all “low priority” issues – they will be ignored for months and eventually closed en masse. See [1] for GitHub milestones.

Otherwise I am fine with the rest of the process.

Thanks,

                Yaron

[1] https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-milestones

From: TXAuth <[email-masked]> on behalf of Aaron Parecki <[email-masked]>
Date: Wednesday, November 25, 2020 at 18:37
To: GNAP Mailing List <[email-masked]>
Subject: [GNAP] GNAP Editors' Use of GitHub Issues

The editors met yesterday to discuss the issues that were pulled out of the previous draft text and document a process for how to resolve these and future issues. We would like to explain how we plan on using labels on GitHub issues to keep track of discussions and keep things moving.

When there are substantive issues or pull requests, the editors will avoid merging or closing those outright, and instead mark them as "pending", so that these can be brought to the attention of the larger group. If no additional discussion happens on these, the merge or close action will be taken in 7 days. Note for this first round we are setting the deadline for the issues below as Dec 11th due to the US holiday and the fact that this is the first time using this process.

"Pending Merge"
When specific text is proposed in a PR (by anyone, not limited to the editors), and the editors believe this text reflects the consensus of the working group, this marks that the PR will be merged in 7 days unless there is a clear alternative proposal accepted by the working group.

"Pending Close"
When the editors believe an issue no longer needs discussion, we'll mark it "Pending Close". The issue will be closed in 7 days unless someone brings new information to the discussion. This tag is not applied to issues that will be closed by a specific pull request.

"Needs Text"
The editors suggest this issue needs additional text in the spec to clarify why this section is needed and under what circumstances. Without a concrete proposal of text to be included in the spec, this section will be removed in a future update.

"Postponed"
This issue can be reconsidered in the future with a more concrete discussion but is not targeted for immediate concrete changes to the spec text. When used on its own, this label does not indicate that an issue is targeted to be closed. An issue may also be marked "Pending Close", and this is used so that we can distinguish closed issues between discussions that have concluded or things that we may want to revisit in the future. Remember that closed issues are not deleted and their contents are still findable and readable, and that new issues can reference closed issues.

With these labels in mind, here are the list of issues and their statuses we were able to discuss on our last editor's call. The action on these pending issues will be taken on Dec 11th to give the group enough time to review this list. For this first round, many of the issues are marked "Pending Close" as we're looking for low hanging fruit to prune the list of issues down. In the future, you can expect to see more "Pending Merge" issues as we're bringing proposed text to review by the WG.

Postponed:

Pending Merge:

* Fetchable Keys

Pending Close:

---

Aaron Parecki

https://aaronparecki.com

-- TXAuth mailing list [email-masked] https://www.ietf.org/mailman/listinfo/txauth

---

From: Dick Hardt <[email-masked]>
Date: Wed, 25 Nov 2020 15:14:40 -0800

What is the process for terminology? Some terms have issues, others don't.

I see a PR for changing RQ to CI -- but it is not clear where the
discussion for that, and other terms will be.

ᐧ

On Wed, Nov 25, 2020 at 10:27 AM Yaron Sheffer <[email-masked]>
wrote:

> I think “postponed” issues should not be closed. Once something is closed,
> we should be reasonably confident that it is resolved for good. People
> rarely search through closed issues.
>
>
>
> Moreover, IMO the label “postponed” is not actionable. Instead, I suggest
> to mark such issues with future milestones, e.g. “IETF110”, meaning that at
> this time we will review the issue. Otherwise, the “postponed” issues will
> probably suffer the destiny of all “low priority” issues – they will be
> ignored for months and eventually closed en masse. See [1] for GitHub
> milestones.
>
>
>
> [1]
> https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-milestones
>
>
>
>
>
> *From: *TXAuth <[email-masked]> on behalf of Aaron Parecki <
> [email-masked]>
> *Date: *Wednesday, November 25, 2020 at 18:37
> *To: *GNAP Mailing List <[email-masked]>
> *Subject: *[GNAP] GNAP Editors' Use of GitHub Issues
>
>
>
> The editors met yesterday to discuss the issues that were pulled out of
> the previous draft text and document a process for how to resolve these and
> When the editors believe an issue no longer needs discussion, we'll mark
> it "Pending Close". The issue will be closed in 7 days unless someone
> brings new information to the discussion. This tag is not applied to issues
> that will be closed by a specific pull request.
>
> The editors suggest this issue needs additional text in the spec to
> clarify why this section is needed and under what circumstances. Without a
> concrete proposal of text to be included in the spec, this section will be
> removed in a future update.
>
> "Postponed"
> -- TXAuth mailing list [email-masked]
> https://www.ietf.org/mailman/listinfo/txauth
> --
> TXAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/txauth
>

---

From: Tom Jones <[email-masked]>
Date: Wed, 25 Nov 2020 16:26:38 -0800

i agree - drop postponed - if you can't say till when, then close. Issues
can always be added by anyone at anytime.
Peace ..tom

---

From: Fabien Imbault <[email-masked]>
Date: Thu, 26 Nov 2020 12:40:25 +0100

Hi all,

I hope you have a great Thanksgiving 🦃

Regarding terminology: it's important work so that we all talk the same
language and people understand the spec more easily. Ideally the editors
(and the chairs I believe) would like to be able to consolidate consensus
on terminology over a relatively short period of time, so that we can all
focus on the core of the spec (a lot of work to do, and this shouldn't stop
us from going forward).

The suggested process is the following :

0) refer to issue 29 and the wiki for the latest state of discussion
https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/29
https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology (serves
as a temporary consolidation of terms, before we can make a PR). It also
provides guidance.

This gives us a good starting point. A scenario could be that we chose to
reuse the current terms (and update definitions), if we don't see concrete
proposals that get positive support from the working group. That's the
fallback strategy. But we'd like to start a phase where we open
the discussion more broadly and see whether we can do better.

*1) please send complete proposals on the mailing list, during the next 2
weeks.  *
Discussions on a single term won't be accepted at this point in time, the
idea being that we'd like to start from a relatively coherent set of terms
and definitions.
Feel free also to comment on the mailing list on other people's proposals :
do you agree? do you object? are there terms we should remove/add? (please
be as factual as possible in your explanations).
The more we can see consensus emerging at this stage the easier it will be.

Please also have a look at "External sources", because we don't want to
live in a vacuum. If existing definitions exist in our field, either reuse
it if it fits our purpose, or explain why you need to change it. Please
don't use a well-known term in a completely different way.

*2) then the editors will propose a consolidated wiki *
The editors will update the wiki, considering :
- ideas and feedback sent on the mailing list, but also
- consistency with the charter's objectives and the rest of the work.

Depending on how it goes, we might already submit a PR (especially if we
see a high level of agreement -> short track).

Then we'll enter into the regular 1 week period to gather comments. Further
discussion/explanations could be managed in a live interim IETF meeting
(since this would be free, a maximum of people would be able to
participate).
At that stage, we should at least agree on the terms used, but their
definitions might still change.

*3) If required: focused/detailed issues on specific terms *
We'll limit the time spent in this last step, with a defined deadline.

*4) W6 Publish a PR and gather consensus for the duration of the work for
the core spec  *
Then hopefully we can achieve consensus from the group. At that point we'll
publish a new draft version with the changes, probably in sync with a
formal IETF meeting (depends on how chairs/editors want to proceed, nothing
has been defined yet, it's just a personal opinion).

In addition to what will be displayed in the wiki, the PR will most
probably change the structure of the document, to include a dedicated
section for terminology. It will also update the rest of the document
accordingly (editing work only).

If new terminology requires specific design work, it shall be handled as
separate issues, but doesn't preclude from including it already in the
terminology. Example : suppose we'd want to separate the AS into a backend
and a frontend (Interaction Server), we could introduce the term but the
implications of that would have to be dealt separately. This example shows
that terminology has potential broader impacts.

5) Before the final draft of the spec is published, I would expect a last
review of the definitions at the end (but the terms wouldn't change), so
that we make sure it is still up to date.
Later, if extensions to the core spec require specific terms, we'll then be
able to expand the terminology.

To summarize, the goal of this process is to keep going forward, and avoid
discussions that very possibly would never end otherwise. We feel it's very
important to get that right in an early stage, so we hope you'll get
involved in the process.

Please comment on this process if needed.
We're waiting for your contributions on the terminology for the next 2
weeks.

Fabien

ps : as highlighted by Dick, the editors have a PR running that concerns
the [Client Instance](
https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/132). This is
linked to work being done on the core spec itself. We'll see if we need to
adjust it as a result, but it doesn't preclude from making the current
version more consistent.

On Thu, Nov 26, 2020 at 12:15 AM Dick Hardt <[email-masked]> wrote:

>> I think “postponed” issues should not be closed. Once something is
>> closed, we should be reasonably confident that it is resolved for good.
>> People rarely search through closed issues.
>>
>>
>>
>> When there are substantive issues or pull requests, the editors will
>> avoid merging or closing those outright, and instead mark them as
>> "pending", so that these can be brought to the attention of the larger
>> group. If no additional discussion happens on these, the merge or close
>> action will be taken in 7 days. Note for this first round we are setting
>> the deadline for the issues below as Dec 11th due to the US holiday and the
>> fact that this is the first time using this process.
>>
>> "Pending Merge"

---

From: Fabien Imbault <[email-masked]>
Date: Fri, 27 Nov 2020 10:03:26 +0100

Hi there,

One of the potential problems we'd like to avoid is to have an ever growing
list of open issues that we never close.

The idea of having milestones (e.g. IETF110) might be a complementary way
of managing priorities.

Editors will revert back to the list after the US vacation days.

Cheers,
Fabien

---

From: Justin Richer <[email-masked]>
Date: Mon, 30 Nov 2020 12:29:07 -0500

With the editor hat on:

A new spec like this is exciting work, and it’s inevitably going to bring in lots of ideas of what it could do and what it could incorporate. These ideas are extremely valuable as they are what push new work into the realms of innovation and possibility and out of the status quo from which it sprang. But there’s a downside to this stream of ideas: most of them aren’t solid enough to incorporate in any way. They’re just loose ideas that maybe we want to consider, but they don’t have anything we can turn to and say “we should build that” or “we shouldn’t build that” since there isn’t any “that” to build. 

The editors have found that many of the issues currently filed seem to fit into this category. There might be an interesting idea in there, but without something specific to tie the idea to, we don’t have a lot to work with as editors, and there are a lot of other items that the group needs to decide and fix first. It’s an issue of triage.

The goal of the “Postponed” tag, as I understand how we’re using it, is to tag issues that might need some future discussion, but we aren’t there yet. Something tagged as “Postponed” but left open long term was meant to flag it as an important detail we should get back to, when we can. Something tagged “Postponed” and closed was meant to flag it as something we might want to revisit, but only when we’ve got something concrete to work against. It’s not meant to say that the group has decided not to do it, it’s meant as a way to acknowledge the input and potentially tie back to it in the future, even if the issue got closed.

It seems like the terminology of “Postponed” didn’t quite capture that intent, and honestly it might not be the best tool for us to use here. I think we we can work with the idea of IETF meeting-based milestones, as has been suggested by several people. The important outcome is that we don’t create a process that’s susceptible to getting buried in “wouldn’t it be nice if…” sentiments to the detriment of forward progress on a functioning protocol. Right now, we’ve got a lot of items that amount to possible future branches, and while we shouldn’t simple forget them, we shouldn’t be focusing energy on them until someone is able to take the effort to explore that branch. At such a time, we can open a new issue and PR’s for that, and link back to these historical artifacts for background and context. By tying such issues to an IETF meeting milestone, we can put some boundaries on items to keep them from languishing. When the milestone comes up, we can evaluate if there’s something to look at yet or not.

 — Justin

> On Nov 27, 2020, at 4:03 AM, Fabien Imbault <[email-masked]> wrote:
> 
> Hi there, 
> 
> One of the potential problems we'd like to avoid is to have an ever growing list of open issues that we never close. 
> 
> The idea of having milestones (e.g. IETF110) might be a complementary way of managing priorities.
> 
> On Thu, Nov 26, 2020 at 1:26 AM Tom Jones <[email-masked] <mailto:[email-masked]>> wrote:
> i agree - drop postponed - if you can't say till when, then close. Issues can always be added by anyone at anytime.
> Peace ..tom
> 
> 
> On Wed, Nov 25, 2020 at 10:27 AM Yaron Sheffer <[email-masked] <mailto:[email-masked]>> wrote:
> [1] https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-milestones <https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-milestones>
>  
> 
>  
> 
> From: TXAuth <[email-masked] <mailto:[email-masked]>> on behalf of Aaron Parecki <[email-masked] <mailto:[email-masked]>>
> To: GNAP Mailing List <[email-masked] <mailto:[email-masked]>>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/131 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/131>
> 
> Pending Merge:
> 
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/129 <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/129>
> 
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/47 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/47>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/64 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/64>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/82 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/82>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/83 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/83>
> 
> Pending Close:
>     
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/100 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/100>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/84 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/84>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/81 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/81>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/76 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/76>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/73 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/73>
> * Unique callback URIs 
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/55 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/55>
> * Instance identifier
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/46 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/46>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/36 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/36>
> ** https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/35 <https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/35>
> ---
> 
> Aaron Parecki
> 
> https://aaronparecki.com <https://aaronparecki.com/>
>  
> 
> -- TXAuth mailing list [email-masked] <mailto:[email-masked]> https://www.ietf.org/mailman/listinfo/txauth <https://www.ietf.org/mailman/listinfo/txauth>-- 
> TXAuth mailing list
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/txauth <https://www.ietf.org/mailman/listinfo/txauth>
> -- 
> TXAuth mailing list
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/txauth <https://www.ietf.org/mailman/listinfo/txauth>
> -- 
> TXAuth mailing list
> [email-masked]