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/docs/enhancements/README.md b/docs/enhancements/README.md new file mode 100644 index 00000000..51bfd853 --- /dev/null +++ b/docs/enhancements/README.md @@ -0,0 +1,23 @@ +# Dex Enhancement Proposal + +## Why do we need it? + +Dex Enhancement Proposal (DEP) is a design document providing information to the community, or describing a new feature for Dex. + +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), [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 [`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/docs/enhancements/_title-YYYY-MM-DD-#issue.md b/docs/enhancements/_title-YYYY-MM-DD-#issue.md new file mode 100644 index 00000000..da671098 --- /dev/null +++ b/docs/enhancements/_title-YYYY-MM-DD-#issue.md @@ -0,0 +1,62 @@ +# Dex Enhancement Proposal (DEP) - - + +## 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 DEP 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.