From 9d89067e62b8c756206c62a594dc5e8caa99d3f5 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 17 Nov 2023 09:04:36 -0500 Subject: [PATCH 1/4] - adds documentation for issues automation --- DEVELOPMENT.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 42347f57af..63300668ea 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -20,11 +20,52 @@ The specification *will evolve over time*. Changes may be made when any of the * Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the *common* and *important* use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. +## Automated closure of issues Process + +In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. + +The following flowchart describes the automation process: + +```mermaid +flowchart TD + openIssue["anyone opens an issue"] + reviewerReplies["a reviewer replies to the issue"] + authorRepliesWithin7Days{"author of the issue replies within 7 days"} + authorRepliesWithin28Days{"author of the issue replies within 28 days"} + reviewerAddsLabel["reviewer adds the Needs author feedback label"] + botAddsMessage["bot adds a message indicating the issue will be closed if the author doesn't reply within 28 days"] + botLabelsRecentActivity["bot adds the No recent activity label"] + botClosesIssue["bot closes the issue as not planned"] + botRemovesNoRecentLabel["bot removes No recent activity label"] + botRemovesNeedsFeedbackLabel["bot removes Needs author feedback label"] + botAddsNeedsAttentionLabel["bot adds Needs attention label"] + reviewerRemovesNeedsAttentionLabel["a reviewer removes the Needs attention label"] + openIssue---->reviewerReplies + reviewerReplies---->reviewerAddsLabel + reviewerAddsLabel---->reviewerRemovesNeedsAttentionLabel + reviewerRemovesNeedsAttentionLabel---->authorRepliesWithin7Days + authorRepliesWithin7Days--"no"-->botLabelsRecentActivity + authorRepliesWithin7Days--"yes"-->botRemovesNeedsFeedbackLabel + botRemovesNeedsFeedbackLabel---->botAddsNeedsAttentionLabel + botLabelsRecentActivity---->botAddsMessage + botAddsMessage---->authorRepliesWithin28Days + authorRepliesWithin28Days--"no"-->botClosesIssue + authorRepliesWithin28Days--"yes"-->botRemovesNoRecentLabel + botRemovesNoRecentLabel---->botAddsNeedsAttentionLabel + botAddsNeedsAttentionLabel---->reviewerReplies +``` + +## Automated TDC agenda issues Process + +An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". + +Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. + ## Specification Change Process For each change in the specification we should *always* consider the following: -* Migration. Is this a construct that has a path from the [existing specification](https://github.com/OAI/OpenAPI-Specification/releases))? If so, how complicated is it to migrate to the proposed change? +* Migration. Is this a construct that has a path from the [existing specification](https://github.com/OAI/OpenAPI-Specification/releases)? If so, how complicated is it to migrate to the proposed change? * Tooling. Strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. From b1b23a27df75da994ed4ba3954bcaa74fd8db812 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 22 Nov 2023 09:18:19 -0500 Subject: [PATCH 2/4] - moves the automation processes to a different section - adds labels descriptions Signed-off-by: Vincent Biret --- DEVELOPMENT.md | 88 +++++++++++++++++++++++++++----------------------- 1 file changed, 47 insertions(+), 41 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 63300668ea..e307e8932a 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -20,47 +20,6 @@ The specification *will evolve over time*. Changes may be made when any of the * Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the *common* and *important* use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. -## Automated closure of issues Process - -In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. - -The following flowchart describes the automation process: - -```mermaid -flowchart TD - openIssue["anyone opens an issue"] - reviewerReplies["a reviewer replies to the issue"] - authorRepliesWithin7Days{"author of the issue replies within 7 days"} - authorRepliesWithin28Days{"author of the issue replies within 28 days"} - reviewerAddsLabel["reviewer adds the Needs author feedback label"] - botAddsMessage["bot adds a message indicating the issue will be closed if the author doesn't reply within 28 days"] - botLabelsRecentActivity["bot adds the No recent activity label"] - botClosesIssue["bot closes the issue as not planned"] - botRemovesNoRecentLabel["bot removes No recent activity label"] - botRemovesNeedsFeedbackLabel["bot removes Needs author feedback label"] - botAddsNeedsAttentionLabel["bot adds Needs attention label"] - reviewerRemovesNeedsAttentionLabel["a reviewer removes the Needs attention label"] - openIssue---->reviewerReplies - reviewerReplies---->reviewerAddsLabel - reviewerAddsLabel---->reviewerRemovesNeedsAttentionLabel - reviewerRemovesNeedsAttentionLabel---->authorRepliesWithin7Days - authorRepliesWithin7Days--"no"-->botLabelsRecentActivity - authorRepliesWithin7Days--"yes"-->botRemovesNeedsFeedbackLabel - botRemovesNeedsFeedbackLabel---->botAddsNeedsAttentionLabel - botLabelsRecentActivity---->botAddsMessage - botAddsMessage---->authorRepliesWithin28Days - authorRepliesWithin28Days--"no"-->botClosesIssue - authorRepliesWithin28Days--"yes"-->botRemovesNoRecentLabel - botRemovesNoRecentLabel---->botAddsNeedsAttentionLabel - botAddsNeedsAttentionLabel---->reviewerReplies -``` - -## Automated TDC agenda issues Process - -An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". - -Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. - ## Specification Change Process For each change in the specification we should *always* consider the following: @@ -142,6 +101,53 @@ However, where a new feature can be introduced in this way, it should be. The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project. +## Automated closure of issues Process + +In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. + +The following flowchart describes the automation process: + +```mermaid +flowchart TD + openIssue["anyone opens an issue"] + reviewerReplies["a reviewer replies to the issue"] + authorRepliesWithin7Days{"author of the issue replies within 7 days"} + authorRepliesWithin28Days{"author of the issue replies within 28 days"} + reviewerAddsLabel["reviewer adds the Needs author feedback label"] + botAddsMessage["bot adds a message indicating the issue will be closed if the author doesn't reply within 28 days"] + botLabelsRecentActivity["bot adds the No recent activity label"] + botClosesIssue["bot closes the issue as not planned"] + botRemovesNoRecentLabel["bot removes No recent activity label"] + botRemovesNeedsFeedbackLabel["bot removes Needs author feedback label"] + botAddsNeedsAttentionLabel["bot adds Needs attention label"] + reviewerRemovesNeedsAttentionLabel["a reviewer removes the Needs attention label"] + openIssue---->reviewerReplies + reviewerReplies---->reviewerAddsLabel + reviewerAddsLabel---->reviewerRemovesNeedsAttentionLabel + reviewerRemovesNeedsAttentionLabel---->authorRepliesWithin7Days + authorRepliesWithin7Days--"no"-->botLabelsRecentActivity + authorRepliesWithin7Days--"yes"-->botRemovesNeedsFeedbackLabel + botRemovesNeedsFeedbackLabel---->botAddsNeedsAttentionLabel + botLabelsRecentActivity---->botAddsMessage + botAddsMessage---->authorRepliesWithin28Days + authorRepliesWithin28Days--"no"-->botClosesIssue + authorRepliesWithin28Days--"yes"-->botRemovesNoRecentLabel + botRemovesNoRecentLabel---->botAddsNeedsAttentionLabel + botAddsNeedsAttentionLabel---->reviewerReplies +``` + +This process makes use of the following labels: + +* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. +* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. +* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. + +## Automated TDC agenda issues Process + +An issue is opened every week, 7 days in advance, for the Technical Direction Committee (TDC), it provides the information to connect the the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". + +Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. + ## Participation While governance of the specification is the role of the TSC, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. From 1b4d56bf73865236ddf8ab3a088228ab17c96823 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 13 Dec 2023 08:12:54 -0500 Subject: [PATCH 3/4] - removes diagram --- DEVELOPMENT.md | 31 ------------------------------- 1 file changed, 31 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index e307e8932a..0c131a1e82 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -105,37 +105,6 @@ The process should be as transparent as possible. Sometimes there will be discus In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. -The following flowchart describes the automation process: - -```mermaid -flowchart TD - openIssue["anyone opens an issue"] - reviewerReplies["a reviewer replies to the issue"] - authorRepliesWithin7Days{"author of the issue replies within 7 days"} - authorRepliesWithin28Days{"author of the issue replies within 28 days"} - reviewerAddsLabel["reviewer adds the Needs author feedback label"] - botAddsMessage["bot adds a message indicating the issue will be closed if the author doesn't reply within 28 days"] - botLabelsRecentActivity["bot adds the No recent activity label"] - botClosesIssue["bot closes the issue as not planned"] - botRemovesNoRecentLabel["bot removes No recent activity label"] - botRemovesNeedsFeedbackLabel["bot removes Needs author feedback label"] - botAddsNeedsAttentionLabel["bot adds Needs attention label"] - reviewerRemovesNeedsAttentionLabel["a reviewer removes the Needs attention label"] - openIssue---->reviewerReplies - reviewerReplies---->reviewerAddsLabel - reviewerAddsLabel---->reviewerRemovesNeedsAttentionLabel - reviewerRemovesNeedsAttentionLabel---->authorRepliesWithin7Days - authorRepliesWithin7Days--"no"-->botLabelsRecentActivity - authorRepliesWithin7Days--"yes"-->botRemovesNeedsFeedbackLabel - botRemovesNeedsFeedbackLabel---->botAddsNeedsAttentionLabel - botLabelsRecentActivity---->botAddsMessage - botAddsMessage---->authorRepliesWithin28Days - authorRepliesWithin28Days--"no"-->botClosesIssue - authorRepliesWithin28Days--"yes"-->botRemovesNoRecentLabel - botRemovesNoRecentLabel---->botAddsNeedsAttentionLabel - botAddsNeedsAttentionLabel---->reviewerReplies -``` - This process makes use of the following labels: * Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. From 39e6aa891b35a4533ecaebb49b9abe35a8ae6aa7 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 13 Dec 2023 08:15:14 -0500 Subject: [PATCH 4/4] - adds clarification to when labels are added removed --- DEVELOPMENT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0c131a1e82..ed6ab0eb4f 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -107,9 +107,9 @@ In an effort to keep the list of issues up to date and easier to navigate throug This process makes use of the following labels: -* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. -* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. -* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. +* Needs author feedback: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. +* No recent activity: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. +* Needs attention: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. ## Automated TDC agenda issues Process