Skip to content

HDDS-14298. [Website v2] Ozone Enhancement Proposals #188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jojochuang wants to merge 2 commits into
base: HDDS-9225-website-v2
Choose a base branch
from
Open

HDDS-14298. [Website v2] Ozone Enhancement Proposals #188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a63093
HDDS-14298: Add Ozone Enhancement Proposals page
jojochuang Dec 31, 2025
26fdf11
Fix
jojochuang Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cspell.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ words:
- EC
- quasi-close
- quasi-closed
- OEP
# Other systems' words
- KDC
- classpath
Expand Down
102 changes: 102 additions & 0 deletions docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
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.
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this doc will become relevant once we switch to the new website which puts docs in the ozone-site repo, where should be put the design docs? I think they should still be tracked with the code base, but we should probably create a dedicated (top level?) directory for them. The website can just link to this location on Github.

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.
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we specify this a little more? I'm not sure it's universally understood what "lazy consensus" means in the context of a pull request.

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
---
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the rest of the docs in the website, I don't think we should be using front-matter for metadata like this since it is all redundant, difficult to keep in sync with more definitive sources like git, and ambiguous in some cases.

title: A sample OEP template
  • This is already indicated by the top level markdown heading.
summary: draft a proposal using this template
  • This is already contained in the document itself per this template.
date: 2025-12-31
  • This is already tracked by the git commit which merges the change, which is less ambiguous as to what actually happened on that date
    • Git can track the day the doc was first created, the day it was merged, and when the corresponding feature was shipped in a release. This field does not specify which of those it is referring to.
jira: HDDS-14298
  • This should be in the doc title and commit message, the later of which is already enforced before a change can be merged.
status: implemented
  • This is already tracked in the git history based on when commits are merged. People usually don't remember to update fields like this in retrospect.
    • For example, the PR would have to be raised with status as draft, this would need to be changed to approved before merging, and then retroactively updated to implemented when the feature is shipped.
author: Wei-Chiu Chuang
  • Also already tracked in git commits, where we can add co-contributors when merging similar to other code changes.

Copy link
Contributor

@errose28 errose28 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After looking at this again in the context of apache/ozone#9664 we might still have a use case for some of the front matter:

authors

Sometimes designs are drafted initially in other platforms like Google docs by multiple people before being shared with the community as the ready-for-review markdown doc, which is just committed by one of the original authors.

jira

The Jira used to file the design doc may be a subtask of the epic used to track the feature development. Having an official link to the epic that corresponds to the scope of the doc would be helpful. A design that is "accepted" has its doc merged, and one that is "implemented" has its Jira epic resolved.

Copy link
Contributor

@errose28 errose28 Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

authors should probably also support a list, like:

authors:
- first author
- second author

<!--
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. See accompanying LICENSE file.
-->

# 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.
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there going to be a "main documentation webpage" with an index of all of these documents? I think we should keep them in the Ozone codebase and have the website link to that directory in the github repo.


# Status
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A markdown doc should only have one top level header. All others should be ## or more.


Defined in the markdown header. Proposed statuses:
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above, this is redundant.


- 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
Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should figure out the workflow we want to use before documenting it. Should we keep approved but in-progress designs in a different directory?

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.

Copy link
Contributor

@errose28 errose28 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's include a section for example use cases.

# 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

```
Loading