From f1014e85640c357279231224b9170f51be94583f Mon Sep 17 00:00:00 2001 From: Danesh Kuruppu Date: Sat, 18 Jan 2025 17:50:49 +0530 Subject: [PATCH 1/4] update proposal guide in development process --- docs/library-development-process.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/library-development-process.md b/docs/library-development-process.md index 366b757d..1c8eb520 100644 --- a/docs/library-development-process.md +++ b/docs/library-development-process.md @@ -2,7 +2,7 @@ _Author_: @shafreenAnfar @ldclakmal _Reviewer_: @daneshk _Created_: 2021/08/26 -_Updated_: 2022/02/23 +_Updated_: 2025/01/20 This section basically discusses the library development process from the inception to materializing it. The goal is to make sure we deliver the best possible library experience we could. The order of each step could be changed a bit but the overall process stays the same. Once a library goes to each step and reaches the end, we can sign it off as a general availability ready library. Each library owner is responsible for making sure their libraries go through these steps before signing off. @@ -14,9 +14,11 @@ The below section discusses each step of this process. Library specification is a structured document which states what needs to be implemented. For an example specification refer to [this](https://github.com/ballerina-platform/module-ballerina-auth/blob/master/docs/spec/spec.md). Once written the specification needs to be committed into the relevant repo under `docs/spec` folder. -In order to update the specification first there should be a proposal. A proposal could be in `draft`, `active`, `rejected`, `accepted` or `implemented` state. Only area leads could reject or accept a given proposal. If accepted, the proposal must be implemented in a branch. Once implemented, the PR must be sent to the main-branch which includes the code changes, the proposal and the specification update. The main idea is since the main-branch is always production ready, the code and the specification must always be in sync with each other. +In order to update the specification first there should be a proposal. The proposal should be in a separate `.md` file under the `stdlib/proposals/` folder in the `ballerina-platform/ballerina-spec` repo. The file should be named such that it is unique and reflects the proposed feature. The filename should be in the format `feature_name.md`. For example, if the proposal is to add contextual logging to the Ballerina log library, the filename could be `contextual_logging.md` and the file should be placed in the `stdlib/proposals/log` folder. -Proposal should clearly state the motivation, description of the solution, goals and none-goals and future work, etc. For an example proposal refer to [this](https://github.com/ballerina-platform/module-ballerina-http/blob/master/docs/proposals/interceptors.md) and the template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once accepted, as mentioned earlier the proposal needs to be committed to the relevant repo under `docs/proposals` folder. +The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and the `Type/Improvement` label and linked to the proposal. This issue should be used to discuss the proposal and get feedback from the community. + +A proposal could be in `submitted`, `rejected`, `accepted` or `implemented` state. The state is maintained in the proposal file itself. If accepted, the proposal must be implemented in a branch. Once implemented, the PR must be sent to the main-branch which includes the code changes, and the specification update. The main idea is since the main-branch is always production ready, the code and the specification must always be in sync with each other. ## Implementation From acafae6a53e5bf6eb030f9bce4d7adfa5164e173 Mon Sep 17 00:00:00 2001 From: Danesh Kuruppu Date: Mon, 20 Jan 2025 10:12:08 +0530 Subject: [PATCH 2/4] Apply suggestions from code review Add review suggestions Co-authored-by: Thisaru Guruge --- docs/library-development-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/library-development-process.md b/docs/library-development-process.md index 1c8eb520..26cd778c 100644 --- a/docs/library-development-process.md +++ b/docs/library-development-process.md @@ -14,7 +14,7 @@ The below section discusses each step of this process. Library specification is a structured document which states what needs to be implemented. For an example specification refer to [this](https://github.com/ballerina-platform/module-ballerina-auth/blob/master/docs/spec/spec.md). Once written the specification needs to be committed into the relevant repo under `docs/spec` folder. -In order to update the specification first there should be a proposal. The proposal should be in a separate `.md` file under the `stdlib/proposals/` folder in the `ballerina-platform/ballerina-spec` repo. The file should be named such that it is unique and reflects the proposed feature. The filename should be in the format `feature_name.md`. For example, if the proposal is to add contextual logging to the Ballerina log library, the filename could be `contextual_logging.md` and the file should be placed in the `stdlib/proposals/log` folder. +In order to update the specification first there should be a proposal. The proposal should be in a separate `.md` file under the `stdlib/proposals/` folder in the [`ballerina-platform/ballerina-spec`](https://github.com/ballerina-platform/ballerina-spec) repo. The file should be named such that it is unique and reflects the proposed feature. The filename should be in the format `feature_name.md`. For example, if the proposal is to add contextual logging to the Ballerina log library, the filename could be `contextual_logging.md` and the file should be placed in the `stdlib/proposals/log` folder. The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and the `Type/Improvement` label and linked to the proposal. This issue should be used to discuss the proposal and get feedback from the community. From abb59f656640be5980395b78060d82ee9ce68544 Mon Sep 17 00:00:00 2001 From: Danesh Kuruppu Date: Mon, 20 Jan 2025 10:24:17 +0530 Subject: [PATCH 3/4] Update docs/library-development-process.md --- docs/library-development-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/library-development-process.md b/docs/library-development-process.md index 26cd778c..878452bd 100644 --- a/docs/library-development-process.md +++ b/docs/library-development-process.md @@ -16,7 +16,7 @@ Library specification is a structured document which states what needs to be imp In order to update the specification first there should be a proposal. The proposal should be in a separate `.md` file under the `stdlib/proposals/` folder in the [`ballerina-platform/ballerina-spec`](https://github.com/ballerina-platform/ballerina-spec) repo. The file should be named such that it is unique and reflects the proposed feature. The filename should be in the format `feature_name.md`. For example, if the proposal is to add contextual logging to the Ballerina log library, the filename could be `contextual_logging.md` and the file should be placed in the `stdlib/proposals/log` folder. -The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and the `Type/Improvement` label and linked to the proposal. This issue should be used to discuss the proposal and get feedback from the community. +The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and the `Type/NewFeature` label and linked to the proposal. This issue should be used to discuss the proposal and get feedback from the community. A proposal could be in `submitted`, `rejected`, `accepted` or `implemented` state. The state is maintained in the proposal file itself. If accepted, the proposal must be implemented in a branch. Once implemented, the PR must be sent to the main-branch which includes the code changes, and the specification update. The main idea is since the main-branch is always production ready, the code and the specification must always be in sync with each other. From c946a9ec6f2545d36d80a2074be8ffb1ef5fe863 Mon Sep 17 00:00:00 2001 From: Danesh Kuruppu Date: Mon, 20 Jan 2025 10:39:01 +0530 Subject: [PATCH 4/4] update the review comments --- docs/library-development-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/library-development-process.md b/docs/library-development-process.md index 878452bd..e43bcc3d 100644 --- a/docs/library-development-process.md +++ b/docs/library-development-process.md @@ -16,7 +16,7 @@ Library specification is a structured document which states what needs to be imp In order to update the specification first there should be a proposal. The proposal should be in a separate `.md` file under the `stdlib/proposals/` folder in the [`ballerina-platform/ballerina-spec`](https://github.com/ballerina-platform/ballerina-spec) repo. The file should be named such that it is unique and reflects the proposed feature. The filename should be in the format `feature_name.md`. For example, if the proposal is to add contextual logging to the Ballerina log library, the filename could be `contextual_logging.md` and the file should be placed in the `stdlib/proposals/log` folder. -The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and the `Type/NewFeature` label and linked to the proposal. This issue should be used to discuss the proposal and get feedback from the community. +The proposal should clearly state the summary, goals and non-goals, motivation, design description, future work, etc. For an example proposal, refer to [this](https://github.com/ballerina-platform/ballerina-spec/blob/master/stdlib/proposals/log/contextual_logging.md). The template can be found [here](https://openjdk.java.net/jeps/2). Basically, the JEP format is followed. Once submitted, a GitHub issue should be created in the `ballerina-platform/ballerina-spec` repo. The issue should be tagged with the `Area/StdLib` label and `Type/Improvement` or `Type/NewFeatue` label as appropriate. This issue should be used to discuss the proposal and get feedback from the community. A proposal could be in `submitted`, `rejected`, `accepted` or `implemented` state. The state is maintained in the proposal file itself. If accepted, the proposal must be implemented in a branch. Once implemented, the PR must be sent to the main-branch which includes the code changes, and the specification update. The main idea is since the main-branch is always production ready, the code and the specification must always be in sync with each other.