HDDS-14298. [Website v2] Ozone Enhancement Proposals#188
HDDS-14298. [Website v2] Ozone Enhancement Proposals#188jojochuang wants to merge 2 commits intoapache:masterfrom
Conversation
Adds a new page to the Developer Guide explaining the Ozone Enhancement Proposals (OEP) process.
jojochuang
added
the
website-v2
errose28
left a comment
errose28
left a comment
There was a problem hiding this comment.
Thanks for starting the discussion on formalizing this process @jojochuang.
| ## 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. |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
| jira: HDDS-14298 | ||
| status: implemented | ||
| author: Wei-Chiu Chuang | ||
| --- |
There was a problem hiding this comment.
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 toapprovedbefore merging, and then retroactively updated toimplementedwhen the feature is shipped.
- For example, the PR would have to be raised with status as
author: Wei-Chiu Chuang
- Also already tracked in git commits, where we can add co-contributors when merging similar to other code changes.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
authors should probably also support a list, like:
authors:
- first author
- second author| 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 |
There was a problem hiding this comment.
A markdown doc should only have one top level header. All others should be ## or more.
| # 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. |
There was a problem hiding this comment.
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 | ||
|
|
||
| Defined in the markdown header. Proposed statuses: |
There was a problem hiding this comment.
Same as above, this is redundant.
| - 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 |
There was a problem hiding this comment.
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?
| # Non-goals | ||
|
|
||
| Very important to define what is outside of the scope of this proposal. | ||
|
|
There was a problem hiding this comment.
Let's include a section for example use cases.
|
Note: Please switch PR target branch to |
3 participants
What changes were proposed in this pull request?
HDDS-14298. [Website v2] Ozone Enhancement Proposals
Please describe your PR in detail:
What is the link to the Apache Jira?
https://issues.apache.org/jira/browse/HDDS-14298
How was this patch tested?
Check off which of the following tests were done on this change. If additional testing was done, please elaborate here as well.