errose28 commented on code in PR #188: URL: https://github.com/apache/ozone-site/pull/188#discussion_r2662476009
########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. Review 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. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- +<!-- + 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. + +# Status Review Comment: A markdown doc should only have one top level header. All others should be `##` or more. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- Review 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 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. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- +<!-- + 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. Review 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. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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. Review 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. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- +<!-- + 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. + +# 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. + Review Comment: Let's include a section for example use cases. ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- +<!-- + 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. + +# 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 Review 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? ########## docs/08-developer-guide/04-project/03-ozone-enhancement-proposals.md: ########## @@ -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. +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 +--- +<!-- + 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. + +# Status + +Defined in the markdown header. Proposed statuses: Review Comment: Same as above, this is redundant. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
