From 7a63093ac53b66410e95bc8961d5c714c3da4a21 Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 31 Dec 2025 12:18:13 -0800 Subject: [PATCH 1/2] HDDS-14298: Add Ozone Enhancement Proposals page Adds a new page to the Developer Guide explaining the Ozone Enhancement Proposals (OEP) process. --- .../03-ozone-enhancement-proposals.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md diff --git a/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md b/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md new file mode 100644 index 0000000000..da779b9ab9 --- /dev/null +++ b/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md @@ -0,0 +1,101 @@ +--- +sidebar_label: Ozone Enhancement Proposals +--- + +# Ozone Enhancement Proposals + +For large features or changes, we use a process called "Ozone Enhancement Proposals" (OEPs) +to ensure that major modifications to Ozone are well-designed and have community consensus. + +If you plan to propose a significant change, please follow the process below +and create a design document *before* you start coding. + +**Note:** Design documents must be in Markdown format. We no longer accept PDFs or Google Docs. + +## OEP Process + +1. **Create a Jira:** Open a dedicated Jira ticket for the proposal. The ticket ID should start with the component prefix (e.g., `HDDS-`) and the title should be prefixed with `[OEP]`. +2. **Write the Design Doc:** Create the design document in Markdown format using the template below. Place the new file in the `hadoop-hdds/docs/content/design` directory. +3. **Submit a Pull Request:** Create a pull request to add the design document to the documentation. +4. **Discuss:** The community will discuss the proposal on the pull request. The discussion follows a lazy consensus model unless a formal vote is called. +5. **Update:** The design document can be updated based on feedback and changes during implementation. + +## Document Template + +The following is the proposed template for an OEP. While it is not mandatory to follow this exact structure, +your proposal should include the following sections. Some proposals may require a different structure +to best convey their design. + +```markdown +--- +title: A sample OEP template +summary: draft a proposal using this template +date: 2025-12-31 +jira: HDDS-14298 +status: implemented +author: Wei-Chiu Chuang +--- + + +### Summary +Provide a one-sentence summary of the proposal, similar to a Jira title. +This will be displayed on the main documentation page and should be concise and informative. + +# Status + +Defined in the markdown header. Proposed statuses: + +- accepted: (Use this as by default. If not accepted, won’t be merged) +- implemented: The discussed technical solution is implemented (maybe with some minor implementation difference) +- replaced: Replaced by a new design doc +- outdated: Code has been changed and design doc doesn’t reflect any more the state of the current code. + +**Note:** Accepted but not-yet-implemented design documents will either be hidden +or placed in a dedicated "in-progress" section to clearly indicate that the feature +is not yet available. + +# Problem statement (Motivation / Abstract) + +What is the problem and how would you solve it? Think about an abstract of a paper: one paragraph overview. +Why will the world better with this change? + +# Non-goals + +Very important to define what is outside of the scope of this proposal. + +# Technical Description (Architecture and implementation details) + +Explain the problem in more details. How can it be reproduced? What is the current solution? +What is the limitation of the current solution? + +How the new proposed solution would solve the problem? Architectural design. + +Implementation details. What should be changed in the code. Is it a huge change? +Do we need to change wire protocol? Backward compatibility? + +### Alternatives +What other alternatives were considered, and why is the proposed solution preferred? +The goal of this section is to help people understand why this is the best solution now, +and also to prevent churn in the future when old alternatives are reconsidered. + +Note: In some cases 4/5 can be combined. For example if you have multiple proposals, +the first version may include multiple solutions. At the end ot the discussion we can move the alternatives to 5. +and explain why the community is decided to use the selected option. + +### Plan +What is the plan for implementing this feature? What is the estimated effort? Does it require a feature branch, +a migration plan, or have other dependencies? This section can be a single sentence or omitted for minor features. + +# References + +``` From 26fdf11cb31ea859ef9667f7bdce9bbcf5c4a720 Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 31 Dec 2025 12:55:21 -0800 Subject: [PATCH 2/2] Fix --- cspell.yaml | 1 + .../03-ozone-enhancement-proposals.md | 17 +++++++++-------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/cspell.yaml b/cspell.yaml index 779abd7a6a..b6fc849662 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -89,6 +89,7 @@ words: - EC - quasi-close - quasi-closed +- OEP # Other systems' words - KDC - classpath diff --git a/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md b/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md index da779b9ab9..8df098d91d 100644 --- a/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md +++ b/docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md @@ -14,11 +14,11 @@ and create a design document *before* you start coding. ## OEP Process -1. **Create a Jira:** Open a dedicated Jira ticket for the proposal. The ticket ID should start with the component prefix (e.g., `HDDS-`) and the title should be prefixed with `[OEP]`. -2. **Write the Design Doc:** Create the design document in Markdown format using the template below. Place the new file in the `hadoop-hdds/docs/content/design` directory. -3. **Submit a Pull Request:** Create a pull request to add the design document to the documentation. -4. **Discuss:** The community will discuss the proposal on the pull request. The discussion follows a lazy consensus model unless a formal vote is called. -5. **Update:** The design document can be updated based on feedback and changes during implementation. +1. **Create a Jira:** Open a dedicated Jira ticket for the proposal. The ticket ID should start with the component prefix (e.g., `HDDS-`) and the title should be prefixed with `[OEP]`. +2. **Write the Design Doc:** Create the design document in Markdown format using the template below. Place the new file in the `hadoop-hdds/docs/content/design` directory. +3. **Submit a Pull Request:** Create a pull request to add the design document to the documentation. +4. **Discuss:** The community will discuss the proposal on the pull request. The discussion follows a lazy consensus model unless a formal vote is called. +5. **Update:** The design document can be updated based on feedback and changes during implementation. ## Document Template @@ -47,7 +47,8 @@ author: Wei-Chiu Chuang limitations under the License. See accompanying LICENSE file. --> -### Summary +# Summary + Provide a one-sentence summary of the proposal, similar to a Jira title. This will be displayed on the main documentation page and should be concise and informative. @@ -83,7 +84,7 @@ How the new proposed solution would solve the problem? Architectural design. Implementation details. What should be changed in the code. Is it a huge change? Do we need to change wire protocol? Backward compatibility? -### Alternatives +# Alternatives What other alternatives were considered, and why is the proposed solution preferred? The goal of this section is to help people understand why this is the best solution now, and also to prevent churn in the future when old alternatives are reconsidered. @@ -92,7 +93,7 @@ Note: In some cases 4/5 can be combined. For example if you have multiple propos the first version may include multiple solutions. At the end ot the discussion we can move the alternatives to 5. and explain why the community is decided to use the selected option. -### Plan +# Plan What is the plan for implementing this feature? What is the estimated effort? Does it require a feature branch, a migration plan, or have other dependencies? This section can be a single sentence or omitted for minor features.