From 38fe0f5319661927819860259570b79c1b233f33 Mon Sep 17 00:00:00 2001 From: "m.nabokikh" Date: Fri, 22 Apr 2022 14:19:15 +0400 Subject: [PATCH 1/3] feat: add enhancement template Signed-off-by: m.nabokikh --- enhancements/README.md | 23 +++++++++ enhancements/_title-YYYY-MM-DD-#issue.md | 62 ++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 enhancements/README.md create mode 100644 enhancements/_title-YYYY-MM-DD-#issue.md diff --git a/enhancements/README.md b/enhancements/README.md new file mode 100644 index 00000000..948897d9 --- /dev/null +++ b/enhancements/README.md @@ -0,0 +1,23 @@ +# Enhancement Proposal + +## Why do we need it? + +Enhancement Proposal (EP) is a design document providing information to the community, or describing a new feature for Dex. + +We intend EPs to be the primary mechanisms for proposing major new features. +This will make it easier for community to describe, track, and look through the history of changes that a going to affect the future development of a product. + +## Process + +### Before starting +1. Search GitHub for [previous issues](https://github.com/dexidp/dex/issues) and [EPs](https://github.com/dexidp/dex/tree/master/enhancements). +2. If an issue does not exist, [open it](https://github.com/dexidp/dex/issues/new?assignees=&labels=&template=feature_request.yaml). +3. Ensure that writing enhancement proposal is necessary for you change by discussing it with a community. + +### Writing an enhancement proposal + +1. Fork the repo. +2. Copy the [`enhancements/_title-YYYY-MM-DD-#issue.md`](enhancements/_title-YYYY-MM-DD-#issue.md) template with the appropriate + name. +3. Fill all sections according to hints in them. Provide as much information as you can. +4. Submit your PR and discuss it with the Dex team. diff --git a/enhancements/_title-YYYY-MM-DD-#issue.md b/enhancements/_title-YYYY-MM-DD-#issue.md new file mode 100644 index 00000000..88b94513 --- /dev/null +++ b/enhancements/_title-YYYY-MM-DD-#issue.md @@ -0,0 +1,62 @@ +# Enhancement Proposal (EP) - - + +## Table of Contents + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals/Pain](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Experience](#user-experience) + - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints) + - [Risks and Mitigations](#risks-and-mitigations) + - [Alternatives](#alternatives) +- [Future Improvements](#future-improvements) + +## Summary + +- Provide a one-paragraph description of the expected change here. + +## Context + +- Link to any previous issues, RFCs, discussions, or briefs. +- Link to any ongoing or future work relevant to this change. + +## Motivation + +### Goals/Pain + +- List work that is assumed to be done in the scope of this enhancement. +- Mention problems solve by this enhancement. + +### Non-goals + +- List work that is entirely out of the scope of this enhancement. Use this to define EP borders to keep work focused. +- All planned future enhancements should be listed in one of the following blocks - Future Improvements. + +## Proposal + +### User Experience + +- Explain your change as if you were describing it to end-users. +- Explain the way users are supposed to use Dex with the proposed enhancement. + +### Implementation Details/Notes/Constraints + +- Explain your change as if you were at a development team meeting (give more technical and implementation details). +- When possible, demonstrate with pseudo-code, not text. +- Be specific. Be opinionated. Avoid ambiguity. + +### Risks and Mitigations + +- Mention all expected risks and migrations in detail here. +- Do not forget to mention if the proposed enhancement is a breaking change. + +### Alternatives + +- What other approaches have been considered, and why did you not choose them? +- What happens if this enhancement will never be accepted and implemented? + +## Future Improvements + +- List any future improvements. From 2571ae9096ff16b5b994f435406cffccfb96e43f Mon Sep 17 00:00:00 2001 From: Maksim Nabokikh <max.nabokih@gmail.com> Date: Mon, 25 Apr 2022 10:33:02 +0400 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mark Sagi-Kazar <mark.sagikazar@gmail.com> Co-authored-by: Márk Sági-Kazár <sagikazarmark@users.noreply.github.com> Signed-off-by: m.nabokikh <maksim.nabokikh@flant.com> --- .github/ISSUE_TEMPLATE/config.yml | 4 ++++ enhancements/README.md | 12 ++++++------ enhancements/_title-YYYY-MM-DD-#issue.md | 4 ++-- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 4e78de20..64156bfa 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -11,3 +11,7 @@ contact_links: - name: 💬 Slack channel url: https://cloud-native.slack.com/messages/dexidp about: Please ask and answer questions here + + - name: 💡 Dex Enhancement Proposal + url: https://github.com/dexidp/dex/tree/master/enhancements/README.md + about: Open a proposal for significant architectural change diff --git a/enhancements/README.md b/enhancements/README.md index 948897d9..f9454581 100644 --- a/enhancements/README.md +++ b/enhancements/README.md @@ -1,17 +1,17 @@ -# Enhancement Proposal +# Dex Enhancement Proposal ## Why do we need it? -Enhancement Proposal (EP) is a design document providing information to the community, or describing a new feature for Dex. +Dex Enhancement Proposal (DEP) is a design document providing information to the community, or describing a new feature for Dex. -We intend EPs to be the primary mechanisms for proposing major new features. -This will make it easier for community to describe, track, and look through the history of changes that a going to affect the future development of a product. +We intend DEPs to be the primary mechanisms for proposing major new features or significant changes to existing ones. +This will make it easier for the community to describe, track, and look through the history of changes that affected the development of the project. ## Process ### Before starting -1. Search GitHub for [previous issues](https://github.com/dexidp/dex/issues) and [EPs](https://github.com/dexidp/dex/tree/master/enhancements). -2. If an issue does not exist, [open it](https://github.com/dexidp/dex/issues/new?assignees=&labels=&template=feature_request.yaml). +1. Search GitHub for previous [issues](https://github.com/dexidp/dex/issues), [discussions](https://github.com/dexidp/dex/discussions) and [DEPs](https://github.com/dexidp/dex/tree/master/enhancements). +2. If a discussion does not exist, [open it](https://github.com/dexidp/dex/discussions/new?category=Ideas). 3. Ensure that writing enhancement proposal is necessary for you change by discussing it with a community. ### Writing an enhancement proposal diff --git a/enhancements/_title-YYYY-MM-DD-#issue.md b/enhancements/_title-YYYY-MM-DD-#issue.md index 88b94513..da671098 100644 --- a/enhancements/_title-YYYY-MM-DD-#issue.md +++ b/enhancements/_title-YYYY-MM-DD-#issue.md @@ -1,4 +1,4 @@ -# Enhancement Proposal (EP) <issue#> - <YYYY-MM-DD> - <title> +# Dex Enhancement Proposal (DEP) <issue#> - <YYYY-MM-DD> - <title> ## Table of Contents @@ -31,7 +31,7 @@ ### Non-goals -- List work that is entirely out of the scope of this enhancement. Use this to define EP borders to keep work focused. +- List work that is entirely out of the scope of this enhancement. Use this to define DEP borders to keep work focused. - All planned future enhancements should be listed in one of the following blocks - Future Improvements. ## Proposal From a98ab893c2791d683162886d36f212aaee92e902 Mon Sep 17 00:00:00 2001 From: "m.nabokikh" <maksim.nabokikh@flant.com> Date: Fri, 20 May 2022 16:19:20 +0400 Subject: [PATCH 3/3] fix: Move enhancements to the docs folder Signed-off-by: m.nabokikh <maksim.nabokikh@flant.com> --- {enhancements => docs/enhancements}/README.md | 4 ++-- .../enhancements}/_title-YYYY-MM-DD-#issue.md | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename {enhancements => docs/enhancements}/README.md (82%) rename {enhancements => docs/enhancements}/_title-YYYY-MM-DD-#issue.md (100%) diff --git a/enhancements/README.md b/docs/enhancements/README.md similarity index 82% rename from enhancements/README.md rename to docs/enhancements/README.md index f9454581..51bfd853 100644 --- a/enhancements/README.md +++ b/docs/enhancements/README.md @@ -10,14 +10,14 @@ This will make it easier for the community to describe, track, and look through ## Process ### Before starting -1. Search GitHub for previous [issues](https://github.com/dexidp/dex/issues), [discussions](https://github.com/dexidp/dex/discussions) and [DEPs](https://github.com/dexidp/dex/tree/master/enhancements). +1. Search GitHub for previous [issues](https://github.com/dexidp/dex/issues), [discussions](https://github.com/dexidp/dex/discussions) and [DEPs](https://github.com/dexidp/dex/tree/master/docs/enhancements). 2. If a discussion does not exist, [open it](https://github.com/dexidp/dex/discussions/new?category=Ideas). 3. Ensure that writing enhancement proposal is necessary for you change by discussing it with a community. ### Writing an enhancement proposal 1. Fork the repo. -2. Copy the [`enhancements/_title-YYYY-MM-DD-#issue.md`](enhancements/_title-YYYY-MM-DD-#issue.md) template with the appropriate +2. Copy the [`docs/enhancements/_title-YYYY-MM-DD-#issue.md`](docs/enhancements/_title-YYYY-MM-DD-#issue.md) template with the appropriate name. 3. Fill all sections according to hints in them. Provide as much information as you can. 4. Submit your PR and discuss it with the Dex team. diff --git a/enhancements/_title-YYYY-MM-DD-#issue.md b/docs/enhancements/_title-YYYY-MM-DD-#issue.md similarity index 100% rename from enhancements/_title-YYYY-MM-DD-#issue.md rename to docs/enhancements/_title-YYYY-MM-DD-#issue.md