diff --git a/.github/ISSUE_TEMPLATE/feature.yaml b/.github/ISSUE_TEMPLATE/feature.yaml index 97508792b..a57eb1e39 100644 --- a/.github/ISSUE_TEMPLATE/feature.yaml +++ b/.github/ISSUE_TEMPLATE/feature.yaml @@ -1,5 +1,5 @@ name: Feature Request -description: File a feature request. +description: File a feature request. title: '[FEATURE]: -

' labels: ['FEATURE','TRIAGE'] body: @@ -7,22 +7,22 @@ body: - type: markdown attributes: value: | -
To expedite issue processing please search open and closed issues before submitting a new one. Existing issues often contain information about workarounds, resolution, or progress updates. +
Before creating the request, see the existing issues to check if your case has not been addressed already. If it has, you may also find information about workarounds, resolution, and progress.
The Design Proposal process is described in the [Design Proposal](https://github.com/open-edge-platform/edge-manageability-framework/design-proposals/README.md) - type: textarea attributes: label: Feature Description - description: A clear and concise description of the problem or missing capability. + description: A clear and concise description of the problem or missing capability. validations: required: true - type: textarea attributes: label: Solution Description - description: If you have a solution in mind, please describe it. + description: If you have a solution in mind, describe it. - type: textarea attributes: label: Alternative Description - description: Have you considered any alternative solutions or workarounds? + description: Have you considered any alternative solutions or workarounds? \ No newline at end of file diff --git a/design-proposals/README.md b/design-proposals/README.md index 02b1e2eae..6fb349932 100644 --- a/design-proposals/README.md +++ b/design-proposals/README.md @@ -2,62 +2,55 @@ ## Introduction -The development process of components in the Open Edge Platform is -design-driven. -Significant changes to the different components, installation scripts, -bare metal agents, APIs simulators, libraries, or tools -must be first discussed, formally documented and agreed upon before they -can be implemented. +The development process of components in the Open Edge Platform is design-driven. +Before implementation, all significant changes to its components, must be first +discussed, formally documented, and agreed upon. +This document describes the whole process. -This document describes the process for proposing, documenting, and -implementing changes. - -To learn more about the different components please check -the [Edge Manageability Framework documentation](https://docs.openedgeplatform.intel.com/edge-manage-docs/main/index.html) +To learn more about the different components, check the +[Edge Manageability Framework documentation](https://docs.openedgeplatform.intel.com/edge-manage-docs/main/index.html) ## The Proposal Process -The proposal process is the process for reviewing a proposal and reaching -a decision about whether to accept or decline the proposal. +The proposal process focuses on reviewing the proposed changes and deciding +if they should be accepted. + + +1. The author of the proposal creates + [a Github issue](https://github.com/open-edge-platform/edge-manageability-framework/issues) + with the `Feature Request` template, briefly describing the new feature. -1. The proposal author - creates [a Github issue](https://github.com/open-edge-platform/edge-manageability-framework/issues) - with the `Feature Request` template describing biefely the new feature.\ - Note: There is no need for a design proposal document at this point.\ + >Note: There is no need for a design proposal document at this point. -2. A discussion on the issue aims to triage the Feature Request with the - Maintainers of the overall project and of the specific sub-project - into one of three outcomes: - - accept the feature request, or - - decline the feature request, or - - ask for a [Design Document](#design-documents), which if merged - becomes an `Architecture Decision Record` (ADR). +2. Maintainers of both the overall project and the sub-project discuss the + issue and decide on one of three outcomes: + - Accept the feature request. + - Decline the feature request. + - Ask for a [Design Document](#design-documents) that, if merged, becomes + an `Architecture Decision Record` (ADR). If the feature request is accepted or declined, the process is done. Otherwise the discussion is expected to identify concerns that should be addressed in more detail in the design document. -3. If requested the proposal author writes - a [Design Document](#design-documents) - to work out details of the proposed design and address the concerns raised - in the initial discussion. - The author create a Pull Request in the `edge-manageability-framework repo` - with a `Proposal` label in it and links - the Pull Request in the original feature issue. +3. If the [Design Document](#design-documents) is requested, the author of the proposed + changes creates it, working out its details and addressing the concerns raised in + the initial discussion. The author create a Pull Request in the `edge-manageability-framework` + repository, assigns it the `Proposal` label, and adds a link to it in the original + feature issue. -4. Once comments and revisions on the design doc wind down, there is a final - discussion on the issue, to reach one of two outcomes: - - accept design document and related feature by merging the Pull Request or - - decline proposal, by closing the Pull Request without merging. +4. Once comments and revisions on the design doc are resolved, the final discussion of the + issue leads to one of two outcomes: + - Accept design document and related feature by merging the Pull Request. + - Decline proposal, by closing the Pull Request without merging. -5. If the Pull request with the Design Document is merged, it means the design - is accepted in the form it's described - and it becomes an **ADR, Architecture Decision Record**. If the Pull Request +5. If the pull request with the Design Document is merged, it means the design is accepted + as described there, and it becomes an **ADR, Architecture Decision Record**. + +After the Pull Request is merged or closed, and its corresponding design is +accepted or declined (whether after step 2 or step 4), implementation work +proceeds in the same way as for any other contribution. -After the Pull Request is merged or closed and it's corresponding design is -accepted or declined (whether after step -2 or step 4), implementation work proceeds in the same way as any other -contribution. ## Detail @@ -66,61 +59,52 @@ contribution. - Make sure that proposals get a proper, fair, timely, recorded evaluation with a clear answer. - Make past proposals easy to find, to avoid duplicated effort. -- If a design doc is needed, make sure contributors know how to write a good - one. +- If a design document is needed, make sure contributors know how to write a + good one. ### Definitions - A **proposal** is a suggestion filed as a Feature Request GitHub issue, - identified by having - the Proposal label. -- A **design document**, is the expanded form of a proposal, - written when the proposal needs more careful explanation and consideration. -- An **ADR, Architecture Decision Record** is the merged version of the **design - document**. + identified by having the Proposal label. +- A **design document**, is the expanded form of a proposal, written when the +proposal needs more careful explanation and consideration. +- An **ADR, Architecture Decision Record** is the merged version of the +**design document**. ### Scope The proposal process should be used for any notable change or addition to the -language, libraries and tools. -“Notable” includes (but is not limited to): +language, libraries, and tools. “Notable” includes (but is not limited to): - New features, such as the addition of a new component or a new user flow. - Major API changes. - UI changes. -- Any other visible behavior changes in existing functionality. +- Any other behavior changes in existing functionality. - Adoption or use of new protocols, protocol versions, cryptographic algorithms, - and the like, - even in an implementation. - -Since proposals begin (and will often end) with the filing of an Feature Request -issue, even -small changes can go through the proposal process if appropriate. -Deciding what is appropriate is matter of judgment we will refine through -experience. + and the like, even in an implementation. + +Because proposals begin (and will often end) with the filing of a Feature Request +issue, even small changes can go through the proposal process if appropriate. +Deciding what is appropriate is a matter of judgment that is constantly refined. If in doubt, file a proposal. -There is a short list of changes that are typically not in scope for the -proposal process: +The following few items do not typically undergo the proposal process: -- Making API changes in internal packages, since those APIs are not publicly - visible. -- Internal per component changes or bug fixes that do not affect the overall +- Making API changes in internal packages, since those APIs are not publicly visible. +- Internal per-component changes or bug fixes that do not affect the overall user experience or any other element. -Again, if in doubt, file a proposal, best case is immediately accepted. +Again, if in doubt, file a proposal. ### Design Documents -As noted above, some (but not all) proposals need to be elaborated in design -document, that if accepted becomes an -Architecture Decision Record (ADR) +As noted above, some (but not all) proposals need to be elaborated on in a design +document. -- The design document should be checked in - to [the proposal directory](https://github.com/open-edge-platform/edge-manageability-framework/tree/main/design-proposals/) - as `NNNN-shortname.md`, - where `NNNN` is the project name (e.g. app-orch) and `shortname` is a short - name (a few dash-separated words at most). +- The design document should be checked in to + [the proposal directory](https://github.com/open-edge-platform/edge-manageability-framework/design-proposals/) + as `NNNN-shortname.md`, where `NNNN` is the project name (e.g. app-orch) and + `shortname` is a few dash-separated words at most. - The design doc should follow [the template](./design-proposal-template.md). @@ -131,60 +115,51 @@ Architecture Decision Record (ADR) revisions. - For ease of review with Github, design documents should be compliant with - the `markdownlit` rules express in this -- repo, that will be checked by `CI`. - The writer can check conformace by issuing the `make lint` command. + the `markdownlit` rules expressed in this repo (you can check conformance + by issuing the `make lint` command). ### Quick Start for Experienced Committers -Experienced committers who are certain that a design doc will be -required for a particular proposal can skip steps 1 and 2 and include the design -doc -with the initial issue. +Experienced committers who are certain that a design doc will be required for a +particular proposal can skip steps 1 and 2 and include the design document with +the initial issue. In the worst case, skipping these steps only leads to an unnecessary design doc. ### Proposal Review The proposal will be discussed in the pull request and if needed one or more -online calls will be established. -At the end of the desicussion the repo maintainer(s) for the involved code will -have the last say for moving the -proposal in one of the following 3 stages. +online calls will be established. At the end of the discussion, the repo +maintainer(s) for the code involved will have the last say in changing the +pull request status to 'Active', 'Accepted', or 'Declined'. #### Active -Issues in the Active column are reviewed weekly in the different teams -to watch for emerging consensus in the discussions. -The maintainers may also comment, make suggestions, -ask clarifying questions, and try to restate the proposals to make sure -everyone agrees about what exactly is being discussed. +Issues in the Active column are reviewed weekly by different teams. Track them +to see emerging consensus in the discussions. The maintainers may also comment, make +suggestions, ask clarifying questions, and try to restate the proposals to make +sure everyone agrees about what exactly is being discussed. #### Accepted -Once a proposal is marked Accepted, the Pull Request is merged or the Issue -closed, the Proposal-Accepted label -is applied, -and the accepted design will be in the `/design-proposals` folder. +Once a proposal is marked as Accepted, the pull request is merged or the Issue +is closed, the Proposal-Accepted label is applied, and the accepted design is put +in the `/design-proposals` folder. -One can apply a release label to signify which release of the Edge Manageability -Framework release will contain -the proposal. +A release label may be added to signify which release of the Edge Microvisor +Toolkit is going to include the proposal. #### Declined A proposal is marked as Declined if a complete re-work is needed, change is not -required anymore or not applicable. -Once a proposal is Declined, the Pull request or the Feature Request it is -closed. +required anymore or not applicable. Once a proposal is Declined, the pull +request or the Feature Request is closed. ## Help -If you need help with this process, please contact the Project's maintainers -contributors by posting to -the [Discussions](https://github.com/open-edge-platform/edge-manageability-framework/discussions) -. +If you need help with this process, contact project maintainers by posting to the +[Discussions](https://github.com/open-edge-platform/edge-manageability-framework/discussions). + To learn about contributing to Edge Manageability Framework in general, see the -[contribution guidelines](https://docs.openedgeplatform.intel.com/edge-manage-docs/main/developer_guide/contributor_guide/index.html) -. +[contribution guidelines](https://docs.openedgeplatform.intel.com/edge-manage-docs/main/developer_guide/contributor_guide/index.html). \ No newline at end of file diff --git a/design-proposals/design-proposal-template.md b/design-proposals/design-proposal-template.md index d35f34bea..60b3f74cc 100644 --- a/design-proposals/design-proposal-template.md +++ b/design-proposals/design-proposal-template.md @@ -14,13 +14,13 @@ solved by the proposed change. Include useful persona flows.] ## Proposal -[A precise statement of the proposed change. Including sub-paragrpahs -and diagrams] +[A precise statement of the proposed change. Including sub-paragraphs and +diagrams.] ## Rationale -[A discussion of alternate approaches that have been considered and the trade -offs, advantages, and disadvantages of the chosen approach.] +[A discussion of alternate approaches that have been considered and the +trade-offs, advantages, and disadvantages of the chosen approach.] ## Affected components and Teams @@ -33,4 +33,4 @@ quarterly release cycle.] ## Open issues (if applicable) [A discussion of issues relating to this proposal for which the author does not -know the solution. This section may be omitted if there are none.] +know the solution. This section may be omitted if there are none.] \ No newline at end of file