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

[Fabien Imbault <[e-mail]>]

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 <[e-mail]> wrote:

> 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 <[e-mail]>
> wrote:
>
>> 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 <[e-mail]> on behalf of Aaron Parecki <
>> [e-mail]>
>> *Date: *Wednesday, November 25, 2020 at 18:37
>> *To: *GNAP Mailing List <[e-mail]>
>> *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.
>>
>> 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
>>
>>
>>
>> -- TXAuth mailing list [e-mail]
>> https://www.ietf.org/mailman/listinfo/txauth
>> --
>> TXAuth mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/txauth
>>
> --
> TXAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/txauth
>