From 1e6198a0047d0e4e1f1fd79269a5b7f3f05368a9 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 10 Oct 2022 16:47:39 +0200 Subject: [PATCH 01/27] doc: document decision process --- doc/decisions/README.md | 12 +--- doc/decisions/decision_process.md | 99 +++++++++++++++++++++++++++++++ doc/decisions/template.md | 20 +++++++ 3 files changed, 120 insertions(+), 11 deletions(-) create mode 100644 doc/decisions/decision_process.md diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 8084cbb716e..17e2bfabb2e 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -1,16 +1,6 @@ # Introduction -We use decision template is based on -[''using patterns to capture architectural decisions''](https://dl.acm.org/doi/10.1109/MS.2007.124) -and [arc42 decisions](http://docs.arc42.org/section-9/) - -Decisions need to: - -- be implementable within the next major release -- be according to [Elektra's goals](/doc/GOALS.md) - -To add a new decision copy `template.md` and add a link in the appropriate -section here. +If you write your first decision, read [Decision Process](decision_process.md). ## Implemented diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md new file mode 100644 index 00000000000..3c2b7b2d498 --- /dev/null +++ b/doc/decisions/decision_process.md @@ -0,0 +1,99 @@ +# Decision Process + +## Problem + +Simply discussing in an issue and then doing an implementation is okay for non-substantial changes. +But substantial decisions must be made transparent and participative way. + +## Constraints + +- All relevant information about decisions must be within Elektra's repository. +- All decisions must go through at least two review rounds, with a merge in between. +- At least two people need to be in favor of the decision in both rounds. + +## Assumptions + +- People want to be informed about or even participate in what Elektra looks like in the future. + +## Considered Alternatives + +- Issues like https://issues.libelektra.org/4521 +- PEPs: https://peps.python.org +- RFCs: https://www.ietf.org/standards/rfcs/ +- Change requests: https://en.wikipedia.org/wiki/Change_request + +## Decision + +Decisions need to: + +- be implementable within the next major release +- be according to [Elektra's goals](/doc/GOALS.md) +- first being decided upon using the decision process described here + +We base our decision process and template on: + +- [''using patterns to capture architectural decisions''](https://dl.acm.org/doi/10.1109/MS.2007.124) +- [arc42 decisions](http://docs.arc42.org/section-9/), and +- [RFCs in rust-lang](https://github.com/rust-lang/rfcs). + +Following subsections describe all steps a decision might run through. +Only two of them are mandatory. + +### Drafts + +The first step is to create a PR with: + +- **one** decision copied from [template.md](template.md), where at least the "Problem" and "Considered Alternatives" are filled out. +- a link from [README.md](README.md) from the "Drafts" section to this decision. + +### In Discussion + +This step is mandatory. + +Here you must ensure: + +- consistency with other decisions +- links from/to related decisions are created +- problem, constraint and assumptions are fully described and sound +- there are several considered alternatives, each with rationale and implication +- decision, rationale and implications is **not** yet filled out if there are people arguing for different options (to keep the discussion unbiased) + +### In Progress + +- You must include all further alternative proposals made in the "Considered Alternatives" section. +- Now it is allowed to have the from the previous round preferred decision in the decision section. + +### Decided + +- decision, rationale and implication are now filled out and fixed according the reviews +- decisions of this status usually already have an implementation PR + +### Mostly Implemented + +This can be useful for decisions that need to be done for every module like plugin or library. +It is for decisions where only a few not-so-important modules are missing and/or issues exist for the remaining pieces. + +### Implemented + +This step is mandatory. + +- Here the details of the decisions are stripped from the decision and moved to the documentation. +- The documentation links to the decision. + +## Rationale + +- The process is lightweight and simple. +- The template helps not forgetting important points. + +## Implications + +The decision process creates at least: + +- two chances to say something to the decision, and +- two commits in the git history. + +## Related Decisions + +## Notes + +Written by Markus Raab 10.10.2022 diff --git a/doc/decisions/template.md b/doc/decisions/template.md index 291b607fcb9..4929fe03c05 100644 --- a/doc/decisions/template.md +++ b/doc/decisions/template.md @@ -4,16 +4,36 @@ ## Constraints +- +- +- + ## Assumptions +- +- +- + ## Considered Alternatives +1. +2. +3. + ## Decision ## Rationale ## Implications +- +- +- + ## Related Decisions +- []() +- []() +- []() + ## Notes From 4894ff638cc464e69109eaedb52e0c6cd2d3775b Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 10 Oct 2022 16:49:33 +0200 Subject: [PATCH 02/27] news: add entry --- doc/news/_preparation_next_release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md index 0c07224d3fe..ade998c595c 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -245,7 +245,7 @@ This section keeps you up-to-date with the multi-language support provided by El ## Documentation -- <> +- Documented [decision process](/doc/decisions/decision_process.md) _(Markus Raab)_ - <> - <> - <> From 0593fec08924f1cf0ae66b3fde1d2052bb36e1fe Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 10 Oct 2022 17:44:30 +0200 Subject: [PATCH 03/27] decision: further points --- doc/decisions/README.md | 2 ++ doc/decisions/decision_process.md | 16 ++++++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 17e2bfabb2e..0b1cd564134 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -67,6 +67,7 @@ If you write your first decision, read [Decision Process](decision_process.md). - [Error Handling](error_handling.md) - [Spec Expressiveness](spec_expressiveness.md) - [Metadata in Spec Namespace](spec_metadata.md) +- [Decision Process](decision_process.md). ## Drafts @@ -77,6 +78,7 @@ If you write your first decision, read [Decision Process](decision_process.md). - [Plugin Variants](plugin_variants.md) - [Global Validation](global_validation.md) +- [Template](template.md) ## Rejected diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 3c2b7b2d498..89807c31155 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -10,6 +10,7 @@ But substantial decisions must be made transparent and participative way. - All relevant information about decisions must be within Elektra's repository. - All decisions must go through at least two review rounds, with a merge in between. - At least two people need to be in favor of the decision in both rounds. +- [Documentation guidelines](/doc/contrib/documentation.md) apply. ## Assumptions @@ -80,17 +81,24 @@ This step is mandatory. - Here the details of the decisions are stripped from the decision and moved to the documentation. - The documentation links to the decision. +### Rejected + +Alternatively, decisions might be rejected (i.e. status quo wins). +These decision PRs are also merged for documentation purposes. + ## Rationale - The process is lightweight and simple. - The template helps not forgetting important points. +- PRs allow to better support the constraint that everything must be within Elektra's repository (also rejected PRs). +- PRs allow to suggest changes and review individual sentences of the decision. ## Implications -The decision process creates at least: - -- two chances to say something to the decision, and -- two commits in the git history. +- Proposal issues are obsolete. +- The decision process creates at least: + - two chances to comment decisions, and + - two commits in the git history. ## Related Decisions From f48bbb524827e10cf08b9238b566a484c9edf1e8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 10 Oct 2022 18:51:53 +0200 Subject: [PATCH 04/27] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Klemens Böswirth <23529132+kodebach@users.noreply.github.com> --- doc/decisions/README.md | 2 +- doc/decisions/decision_process.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 0b1cd564134..204d3072598 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -1,6 +1,6 @@ # Introduction -If you write your first decision, read [Decision Process](decision_process.md). +Before you write your first decision, read [Decision Process](decision_process.md). ## Implemented diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 89807c31155..182d61b8319 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -3,7 +3,7 @@ ## Problem Simply discussing in an issue and then doing an implementation is okay for non-substantial changes. -But substantial decisions must be made transparent and participative way. +But substantial decisions must be made transparently and in a participative way. ## Constraints @@ -62,11 +62,11 @@ Here you must ensure: ### In Progress - You must include all further alternative proposals made in the "Considered Alternatives" section. -- Now it is allowed to have the from the previous round preferred decision in the decision section. +- Now it is allowed to have the ??? from the previous round's preferred decision in the decision section. ### Decided -- decision, rationale and implication are now filled out and fixed according the reviews +- decision, rationale and implication are now filled out and fixed according to the reviews - decisions of this status usually already have an implementation PR ### Mostly Implemented @@ -80,6 +80,7 @@ This step is mandatory. - Here the details of the decisions are stripped from the decision and moved to the documentation. - The documentation links to the decision. +- The decision links to the new documentation. ### Rejected From 9d221f7c36d58e9bd0ae0bb1bdf38c3ac34fce9f Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:36:02 +0200 Subject: [PATCH 05/27] fixes of commited suggestions --- doc/decisions/decision_process.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 182d61b8319..39e250564f9 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -33,13 +33,16 @@ Decisions need to: We base our decision process and template on: -- [''using patterns to capture architectural decisions''](https://dl.acm.org/doi/10.1109/MS.2007.124) -- [arc42 decisions](http://docs.arc42.org/section-9/), and +- [''using patterns to capture architectural decisions''](https://dl.acm.org/doi/10.1109/MS.2007.124), +- [arc42 decisions](http://docs.arc42.org/section-9/), +- [ADR](https://adr.github.io/), and - [RFCs in rust-lang](https://github.com/rust-lang/rfcs). Following subsections describe all steps a decision might run through. Only two of them are mandatory. +Explanations of the template are in [explanations.md](explanations.md). + ### Drafts The first step is to create a PR with: @@ -62,7 +65,7 @@ Here you must ensure: ### In Progress - You must include all further alternative proposals made in the "Considered Alternatives" section. -- Now it is allowed to have the ??? from the previous round's preferred decision in the decision section. +- Now it is allowed to have the decision from the previous round in the "Decision" section. ### Decided From a5de988be48f6a528bca571c7113351b63452d82 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:36:53 +0200 Subject: [PATCH 06/27] added explanations --- doc/decisions/README.md | 1 + doc/decisions/explanations.md | 91 +++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 doc/decisions/explanations.md diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 204d3072598..93d085ce42a 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -79,6 +79,7 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Plugin Variants](plugin_variants.md) - [Global Validation](global_validation.md) - [Template](template.md) +- [Explanations](explanations.md) ## Rejected diff --git a/doc/decisions/explanations.md b/doc/decisions/explanations.md new file mode 100644 index 00000000000..395201caed2 --- /dev/null +++ b/doc/decisions/explanations.md @@ -0,0 +1,91 @@ +# Explanations + +## Problem + +Clearly define: + +- the context in which the problem exists +- your observation of the problem +- ideally an example for that problem + +## Constraints + +List all constraints given by: + +- use cases +- requirements +- [Elektra's goals](/doc/GOALS.md) +- guidelines, e.g. [documentation guidelines](/doc/contrib/documentation.md) +- standards, e.g. [C99](https://www.open-std.org/jtc1/sc22/wg14/) +- other decisions +- the scope (i.e. describe what shouldn't change) + +> Note: +> The decision (but not necessarily the considered alternatives) must fulfill all constraints. + +## Assumptions + +Often we are quite blind and do not see assumptions we have. +So this section needs special care and honesty. +Assumptions is what we believe to be true but do not or cannot really know, e.g.: + +- what users will accept +- perceived usability +- if the implementation will be faster/slower +- estimations of costs +- problems/risks that might turn up + +> Note: +> The decision (but not necessarily the considered alternatives) must fulfill all assumptions. + +## Considered Alternatives + +This is a list of all solutions and a rationale why the solution was not taken, e.g. because: + +- the solution does not solve the whole problem +- some constraints or assumptions are violated +- another solution: + - solves the problem better + - is more in line with Elektra's architecture + - better supports Elektra's goals + - better fulfills non-functional requirements + +## Decision + +Here should be a detailed description of the best solution, i.e., the decision. +It should: + +- give all details why the solution: + - the solution solves the problem best + - is best in line with our goals + - fulfills all constraints and assumptions +- describe what needs to be changed +- make clear how the implementation should be done + +## Rationale + +Here is the description why the decision is the best solution. +Also describe all drawbacks the solution has. + +## Implications + +Here is a full description of everything that the decision will change or whatever needs to be changed because of the decision. +This can be: + +- affect on other decisions, goals, etc. +- non-obvious implementation tasks, e.g. changing in different needs to be implemented +- which issues get solved +- which documentation needs to be updated +- which concepts change +- which guarantees are added/removed + +## Related Decisions + +This section has links to other decisions with description what the relation is. +Decisions that give constraints must be listed in "Constraints" above. + +## Notes + +Here is a full list of off-line discussions, issue trackers, PRs etc. related to this decision. +Furthermore, the author, acknowledgements, dates etc. can be written here. + From c6c5008bf1d96db43909a351d038f8811b255b2e Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:40:38 +0200 Subject: [PATCH 07/27] clarify "in discussion" --- doc/decisions/decision_process.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 39e250564f9..cbd01b9d8bf 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -62,6 +62,9 @@ Here you must ensure: - there are several considered alternatives, each with rationale and implication - decision, rationale and implications is **not** yet filled out if there are people arguing for different options (to keep the discussion unbiased) +Here "the decision" should not have one decision but several well-described solutions. +So for several solutions a proposal, rationale and implication should be given. + ### In Progress - You must include all further alternative proposals made in the "Considered Alternatives" section. From 6a9f1d380a4c4f3c09e288805de0e82a11123416 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:42:23 +0200 Subject: [PATCH 08/27] more details about how decision process works --- doc/decisions/decision_process.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index cbd01b9d8bf..b2aaad4b889 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -11,10 +11,14 @@ But substantial decisions must be made transparently and in a participative way. - All decisions must go through at least two review rounds, with a merge in between. - At least two people need to be in favor of the decision in both rounds. - [Documentation guidelines](/doc/contrib/documentation.md) apply. +- During the decision process, the PRs constantly get updated. + Questions in the PRs are answered by updating the PR and answering with the commit id. ## Assumptions - People want to be informed about or even participate in what Elektra looks like in the future. +- We will always be able to reach an consensus. + We don't need a vote or a benevolent dictatorship. ## Considered Alternatives @@ -65,6 +69,8 @@ Here you must ensure: Here "the decision" should not have one decision but several well-described solutions. So for several solutions a proposal, rationale and implication should be given. +This step is finished when every reviewer approves. + ### In Progress - You must include all further alternative proposals made in the "Considered Alternatives" section. @@ -88,6 +94,8 @@ This step is mandatory. - The documentation links to the decision. - The decision links to the new documentation. +This step is finished when every reviewer approves. + ### Rejected Alternatively, decisions might be rejected (i.e. status quo wins). From f77ce41011a27c5e7817757d5b4a73f41a386dce Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:52:57 +0200 Subject: [PATCH 09/27] decisions: answer why starting early --- doc/decisions/decision_process.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index b2aaad4b889..16dfa759961 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -19,6 +19,8 @@ But substantial decisions must be made transparently and in a participative way. - People want to be informed about or even participate in what Elektra looks like in the future. - We will always be able to reach an consensus. We don't need a vote or a benevolent dictatorship. +- Unlike the Rust Decision process, decisions in Elektra do not have a disadvantage if they were flawed in early stages. + Only the end results counts. ## Considered Alternatives @@ -119,4 +121,8 @@ These decision PRs are also merged for documentation purposes. ## Notes +- Early discussions in issues or in discussions is not prohibited. + They don't bring a decision forward, though. + To not waste time, it is recommended to start with the decision process as described here asap. + Written by Markus Raab 10.10.2022 From 326eaffa70174085e39cdc44834159f4a25d9b26 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 18:58:53 +0200 Subject: [PATCH 10/27] decisions: adopt Rust guidelines --- doc/decisions/decision_process.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 16dfa759961..c01f642bf39 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -11,8 +11,11 @@ But substantial decisions must be made transparently and in a participative way. - All decisions must go through at least two review rounds, with a merge in between. - At least two people need to be in favor of the decision in both rounds. - [Documentation guidelines](/doc/contrib/documentation.md) apply. -- During the decision process, the PRs constantly get updated. - Questions in the PRs are answered by updating the PR and answering with the commit id. +- During the decision process, the PRs constantly get updated: + - Make changes as new commits to the pull request. + - Questions in the PRs are answered by updating the PR and answering with the commit id. + - As generally recommended in Elektra, do not squash after they are visible on the pull request. + - Rebase only if the decision was already accepted and has a merge conflict. ## Assumptions From 54affcbab5e5e4c139f56b111c5e6b35b587ddff Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 19:02:30 +0200 Subject: [PATCH 11/27] decisions: code review comments --- doc/decisions/decision_process.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index c01f642bf39..1122a21be22 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -16,6 +16,9 @@ But substantial decisions must be made transparently and in a participative way. - Questions in the PRs are answered by updating the PR and answering with the commit id. - As generally recommended in Elektra, do not squash after they are visible on the pull request. - Rebase only if the decision was already accepted and has a merge conflict. +- For reviewers: + - Prefer to directly give suggestions how to change sentences. + - General points should be asked in the root of "Conversation" and not at random sentences in the review. ## Assumptions From 7434bb2df6b892ff82523a43bf403525454a1053 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 19:05:50 +0200 Subject: [PATCH 12/27] decisions: explain why issues are not a good idea --- doc/decisions/decision_process.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 1122a21be22..a03bcf022b1 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -112,7 +112,8 @@ These decision PRs are also merged for documentation purposes. ## Rationale - The process is lightweight and simple. -- The template helps not forgetting important points. +- The template makes sure important points are not forgotten. +- Every decision is by design in its own file with its own git history. - PRs allow to better support the constraint that everything must be within Elektra's repository (also rejected PRs). - PRs allow to suggest changes and review individual sentences of the decision. From d9aa199d8ce3f92cbd834e379cd9ff7033ec7077 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 19:07:57 +0200 Subject: [PATCH 13/27] decisions: suggestion from @kodebach --- doc/decisions/README.md | 2 +- doc/decisions/decision_process.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 93d085ce42a..b14f178a358 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -34,7 +34,7 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Memory Layout](memory_layout.md) - [Backend Plugin](backend_plugin.md) -## Mostly Implemented +## Partially Implemented - [Hooks](hooks.md) (@atmaxinger) - [Array for Warnings](warning_array.md) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index a03bcf022b1..0e8fcf83ed2 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -89,11 +89,13 @@ This step is finished when every reviewer approves. - decision, rationale and implication are now filled out and fixed according to the reviews - decisions of this status usually already have an implementation PR -### Mostly Implemented +### Partially Implemented This can be useful for decisions that need to be done for every module like plugin or library. It is for decisions where only a few not-so-important modules are missing and/or issues exist for the remaining pieces. +The "Implication" must clearly say how much of the decision is already implemented. + ### Implemented This step is mandatory. From 47a9285072de6658c5d14ff708b804d95f05b5c5 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 11 Oct 2022 19:26:58 +0200 Subject: [PATCH 14/27] news: add decisions fix small formatting problem --- doc/decisions/explanations.md | 1 - doc/news/_preparation_next_release.md | 32 +++++++++++++++++++++++++++ doc/todo/NEWS.md | 18 +++++++++++++++ 3 files changed, 50 insertions(+), 1 deletion(-) diff --git a/doc/decisions/explanations.md b/doc/decisions/explanations.md index 395201caed2..ddf343e6d3d 100644 --- a/doc/decisions/explanations.md +++ b/doc/decisions/explanations.md @@ -88,4 +88,3 @@ Decisions that give constraints must be listed in "Constraints" above. Here is a full list of off-line discussions, issue trackers, PRs etc. related to this decision. Furthermore, the author, acknowledgements, dates etc. can be written here. - diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md index ade998c595c..db21d2acdf9 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -245,6 +245,38 @@ This section keeps you up-to-date with the multi-language support provided by El ## Documentation +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> + +### Decisions + - Documented [decision process](/doc/decisions/decision_process.md) _(Markus Raab)_ - <> - <> diff --git a/doc/todo/NEWS.md b/doc/todo/NEWS.md index 00b617f06b0..bfa15d4df57 100644 --- a/doc/todo/NEWS.md +++ b/doc/todo/NEWS.md @@ -275,6 +275,24 @@ This section keeps you up-to-date with the multi-language support provided by El - <> - <> +### Decisions + +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> +- <> + ### Tutorials - <> From 189a55d41b7cba9c78341d69b35524c5051d579e Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 06:34:37 +0200 Subject: [PATCH 15/27] decisions: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Klemens Böswirth <23529132+kodebach@users.noreply.github.com> Co-authored-by: Maximilian Irlinger --- doc/decisions/decision_process.md | 6 +++--- doc/decisions/explanations.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 0e8fcf83ed2..281a256dca5 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -14,11 +14,11 @@ But substantial decisions must be made transparently and in a participative way. - During the decision process, the PRs constantly get updated: - Make changes as new commits to the pull request. - Questions in the PRs are answered by updating the PR and answering with the commit id. - - As generally recommended in Elektra, do not squash after they are visible on the pull request. + - As generally recommended in Elektra, do not squash commits after they are visible on the pull request. - Rebase only if the decision was already accepted and has a merge conflict. - For reviewers: - Prefer to directly give suggestions how to change sentences. - - General points should be asked in the root of "Conversation" and not at random sentences in the review. + - General questions should be asked in the root of "Conversation" and not at random sentences in the review. ## Assumptions @@ -41,7 +41,7 @@ Decisions need to: - be implementable within the next major release - be according to [Elektra's goals](/doc/GOALS.md) -- first being decided upon using the decision process described here +- first be decided upon using the decision process described here We base our decision process and template on: diff --git a/doc/decisions/explanations.md b/doc/decisions/explanations.md index ddf343e6d3d..15b4e52d5cb 100644 --- a/doc/decisions/explanations.md +++ b/doc/decisions/explanations.md @@ -36,7 +36,7 @@ Assumptions is what we believe to be true but do not or cannot really know, e.g. - problems/risks that might turn up > Note: -> The decision (but not necessarily the considered alternatives) must fulfill all assumptions. +> The decision (but not necessarily the considered alternatives) must not break any assumptions. ## Considered Alternatives @@ -56,7 +56,7 @@ Here should be a detailed description of the best solution, i.e., the decision. It should: - give all details why the solution: - - the solution solves the problem best + - solves the problem best - is best in line with our goals - fulfills all constraints and assumptions - describe what needs to be changed From 8c290db5f93e45cc0c64d2d04b64c26cdd12fa13 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 06:39:47 +0200 Subject: [PATCH 16/27] decisions: rename to TEMPLATE and EXPLANATIONS --- doc/decisions/{explanations.md => EXPLANATIONS.md} | 2 +- doc/decisions/README.md | 9 +++++++-- doc/decisions/{template.md => TEMPLATE.md} | 2 +- 3 files changed, 9 insertions(+), 4 deletions(-) rename doc/decisions/{explanations.md => EXPLANATIONS.md} (99%) rename doc/decisions/{template.md => TEMPLATE.md} (94%) diff --git a/doc/decisions/explanations.md b/doc/decisions/EXPLANATIONS.md similarity index 99% rename from doc/decisions/explanations.md rename to doc/decisions/EXPLANATIONS.md index 15b4e52d5cb..5543eed2513 100644 --- a/doc/decisions/explanations.md +++ b/doc/decisions/EXPLANATIONS.md @@ -1,4 +1,4 @@ -# Explanations +# EXPLANATIONS ## Problem diff --git a/doc/decisions/README.md b/doc/decisions/README.md index b14f178a358..9a38d639d69 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -78,8 +78,6 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Plugin Variants](plugin_variants.md) - [Global Validation](global_validation.md) -- [Template](template.md) -- [Explanations](explanations.md) ## Rejected @@ -89,3 +87,10 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Elektra Web Publish Subscribe](elektra_web_pubsub.md) - [Internal Cache](internal_cache.md) - [Vendor Spec](vendor_spec.md) + +## Meta-Information + +Even though they use the decision template, following decisions are not real decisions: + +- [Template](TEMPLATE.md) +- [Explanations](EXPLANATIONS.md) diff --git a/doc/decisions/template.md b/doc/decisions/TEMPLATE.md similarity index 94% rename from doc/decisions/template.md rename to doc/decisions/TEMPLATE.md index 4929fe03c05..eea349c789b 100644 --- a/doc/decisions/template.md +++ b/doc/decisions/TEMPLATE.md @@ -1,4 +1,4 @@ -# Template +# TEMPLATE ## Problem From c1b03aed5d8036d2a7ce5c2337b0dc28af786e97 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 07:14:36 +0200 Subject: [PATCH 17/27] decisions: as suggested by @atmaxinger --- doc/decisions/decision_process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 281a256dca5..8f498bb06e0 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -24,7 +24,7 @@ But substantial decisions must be made transparently and in a participative way. - People want to be informed about or even participate in what Elektra looks like in the future. - We will always be able to reach an consensus. - We don't need a vote or a benevolent dictatorship. + We don't need a vote (besides the approved review) or a benevolent dictatorship. - Unlike the Rust Decision process, decisions in Elektra do not have a disadvantage if they were flawed in early stages. Only the end results counts. @@ -45,7 +45,7 @@ Decisions need to: We base our decision process and template on: -- [''using patterns to capture architectural decisions''](https://dl.acm.org/doi/10.1109/MS.2007.124), +- [''using patterns to capture architectural decisions''](http://eprints.cs.univie.ac.at/2345/1/02_Using_Patterns_to_Capture.pdf), - [arc42 decisions](http://docs.arc42.org/section-9/), - [ADR](https://adr.github.io/), and - [RFCs in rust-lang](https://github.com/rust-lang/rfcs). From 08ead559b988b016b18ce46684ebf758680206da Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 07:55:04 +0200 Subject: [PATCH 18/27] decisions: further small updates --- doc/decisions/EXPLANATIONS.md | 5 ++++- doc/decisions/decision_process.md | 6 +++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 5543eed2513..3e3fc72cc2c 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -72,7 +72,7 @@ Also describe all drawbacks the solution has. Here is a full description of everything that the decision will change or whatever needs to be changed because of the decision. This can be: -- affect on other decisions, goals, etc. +- effect on other decisions, goals, etc. - non-obvious implementation tasks, e.g. changing in different needs to be implemented - which issues get solved - which documentation needs to be updated @@ -87,4 +87,7 @@ Decisions that give constraints must be listed in "Constraints" above. ## Notes Here is a full list of off-line discussions, issue trackers, PRs etc. related to this decision. +Preferable it is linked, but if it is not possible, it can also be in full-text here. +If particular information is important and not present in any sections above, please quote it here. + Furthermore, the author, acknowledgements, dates etc. can be written here. diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 8f498bb06e0..8b48200187e 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -3,7 +3,7 @@ ## Problem Simply discussing in an issue and then doing an implementation is okay for non-substantial changes. -But substantial decisions must be made transparently and in a participative way. +But substantial decisions must be made in a transparent and participative way. ## Constraints @@ -23,6 +23,8 @@ But substantial decisions must be made transparently and in a participative way. ## Assumptions - People want to be informed about or even participate in what Elektra looks like in the future. +- People writing or reviewing decisions want Elektra to improve, so they also want to accept (acceptable) decisions. + In general they also want change if it brings Elektra towards its [goals](/doc/GOALS.md) (but doesn't violate Elektra's stability guarantees). - We will always be able to reach an consensus. We don't need a vote (besides the approved review) or a benevolent dictatorship. - Unlike the Rust Decision process, decisions in Elektra do not have a disadvantage if they were flawed in early stages. @@ -118,6 +120,8 @@ These decision PRs are also merged for documentation purposes. - Every decision is by design in its own file with its own git history. - PRs allow to better support the constraint that everything must be within Elektra's repository (also rejected PRs). - PRs allow to suggest changes and review individual sentences of the decision. +- Several "Related Decisions" are very important even if everyone agrees on one solution. + They allow reviewers and future readers of the decision to understand which options were considered and why they were rejected. ## Implications From 2b1c608188b99a49409cdfbab60562469003dcb4 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 08:08:15 +0200 Subject: [PATCH 19/27] decision: write assumption about experts --- doc/decisions/decision_process.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 8b48200187e..eeabf9579cf 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -13,7 +13,12 @@ But substantial decisions must be made in a transparent and participative way. - [Documentation guidelines](/doc/contrib/documentation.md) apply. - During the decision process, the PRs constantly get updated: - Make changes as new commits to the pull request. - - Questions in the PRs are answered by updating the PR and answering with the commit id. + - Questions in the PRs are answered by: + 1. updating the PR + 2. either: + - reply with a quote of the change and the commit SHA-ID + - reply with a diff of the change + - give a thumbs-up if the change was done exactly as suggested - As generally recommended in Elektra, do not squash commits after they are visible on the pull request. - Rebase only if the decision was already accepted and has a merge conflict. - For reviewers: @@ -29,6 +34,9 @@ But substantial decisions must be made in a transparent and participative way. We don't need a vote (besides the approved review) or a benevolent dictatorship. - Unlike the Rust Decision process, decisions in Elektra do not have a disadvantage if they were flawed in early stages. Only the end results counts. +- Different to initiatives like Rust, most contributors in Elektra are not experts in configuration management or programming languages. + So we do not expect that a clear problem or solution is in the decision's write mind beforehand. + Instead the decisions is also a supported learning process about the problem and solution. ## Considered Alternatives From 10805cd1c3615a5e1dd35ad2f29733e0a0a32db9 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 08:14:32 +0200 Subject: [PATCH 20/27] decisions: further fix of sentences --- doc/decisions/decision_process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index eeabf9579cf..057b1f36e18 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -35,8 +35,8 @@ But substantial decisions must be made in a transparent and participative way. - Unlike the Rust Decision process, decisions in Elektra do not have a disadvantage if they were flawed in early stages. Only the end results counts. - Different to initiatives like Rust, most contributors in Elektra are not experts in configuration management or programming languages. - So we do not expect that a clear problem or solution is in the decision's write mind beforehand. - Instead the decisions is also a supported learning process about the problem and solution. + So we do not expect that a clear problem or solution is in the decision writer's mind beforehand. + Instead the decision process is a supported learning process. ## Considered Alternatives From 4425635d89c57b5c4798c95a71281ded6dd87ef8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 08:46:20 +0200 Subject: [PATCH 21/27] decisions: fix links --- doc/contrib/documentation.md | 2 +- doc/decisions/decision_process.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/contrib/documentation.md b/doc/contrib/documentation.md index d02d25c8b38..66b456318ef 100644 --- a/doc/contrib/documentation.md +++ b/doc/contrib/documentation.md @@ -134,4 +134,4 @@ In general we use [arc42.org](https://arc42.org/) but we use specialized templat - [libs](/src/libs/template/README.md). - [bindings](/src/bindings/template/README.md). - [tools](/src/tools/template/README.md). -- [decisions](/doc/decisions/template.md) +- [decisions](/doc/decisions/TEMPLATE.md) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 057b1f36e18..c6417061a3a 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -63,13 +63,13 @@ We base our decision process and template on: Following subsections describe all steps a decision might run through. Only two of them are mandatory. -Explanations of the template are in [explanations.md](explanations.md). +Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). ### Drafts The first step is to create a PR with: -- **one** decision copied from [template.md](template.md), where at least the "Problem" and "Considered Alternatives" are filled out. +- **one** decision copied from [TEMPLATE.md](TEMPLATE.md), where at least the "Problem" and "Considered Alternatives" are filled out. - a link from [README.md](README.md) from the "Drafts" section to this decision. ### In Discussion From 1dffa6cffed096a69f9b98a33f6eb3528c525c2d Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 08:47:25 +0200 Subject: [PATCH 22/27] decisions: make sentence shorter --- doc/decisions/decision_process.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index c6417061a3a..da49370e54b 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -63,13 +63,14 @@ We base our decision process and template on: Following subsections describe all steps a decision might run through. Only two of them are mandatory. +We use the template [TEMPLATE.md](TEMPLATE.md). Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). ### Drafts The first step is to create a PR with: -- **one** decision copied from [TEMPLATE.md](TEMPLATE.md), where at least the "Problem" and "Considered Alternatives" are filled out. +- **one** decision, where at least the "Problem" and "Considered Alternatives" are filled out. - a link from [README.md](README.md) from the "Drafts" section to this decision. ### In Discussion From 4e7ea68c695c9096fe836f446a38ea7aa46c36f8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Wed, 12 Oct 2022 08:48:32 +0200 Subject: [PATCH 23/27] decisions: accepting suggested changes --- doc/decisions/decision_process.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index da49370e54b..82a3619b106 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -16,6 +16,7 @@ But substantial decisions must be made in a transparent and participative way. - Questions in the PRs are answered by: 1. updating the PR 2. either: + - accept the suggested change - reply with a quote of the change and the commit SHA-ID - reply with a diff of the change - give a thumbs-up if the change was done exactly as suggested From 967f4d292cd15d61cea71e41a4d64093f9ab7fe5 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 13 Oct 2022 11:40:57 +0200 Subject: [PATCH 24/27] decisions: last adoptions --- doc/decisions/decision_process.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 82a3619b106..f6a94943f1f 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -14,12 +14,12 @@ But substantial decisions must be made in a transparent and participative way. - During the decision process, the PRs constantly get updated: - Make changes as new commits to the pull request. - Questions in the PRs are answered by: - 1. updating the PR - 2. either: - - accept the suggested change - - reply with a quote of the change and the commit SHA-ID - - reply with a diff of the change - - give a thumbs-up if the change was done exactly as suggested + 1. Update the PR and incorporate the review. + 2. Reply on GitHub: + - Give a short summary of what you did in a single comment, and reply to individual questions if necessary. + - Link to commit SHA-IDs for details. + 3. Mark all GitHub threads as resolved, if you incorporated the feedback as suggested. + Committing a suggestion directly on GitHub does this automatically. - As generally recommended in Elektra, do not squash commits after they are visible on the pull request. - Rebase only if the decision was already accepted and has a merge conflict. - For reviewers: @@ -86,8 +86,8 @@ Here you must ensure: - there are several considered alternatives, each with rationale and implication - decision, rationale and implications is **not** yet filled out if there are people arguing for different options (to keep the discussion unbiased) -Here "the decision" should not have one decision but several well-described solutions. -So for several solutions a proposal, rationale and implication should be given. +Here "the decision" should not only have one decision but should describe several solutions. +For each solution a proposal, rationale and implication should be given. This step is finished when every reviewer approves. From 2662703286b200f44542aba3517274cc9b5ab27a Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 13 Oct 2022 11:58:32 +0200 Subject: [PATCH 25/27] decisions: add manpages --- doc/decisions/README.md | 1 + doc/decisions/TEMPLATE.md | 12 ++++++------ doc/decisions/manpages.md | 40 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 doc/decisions/manpages.md diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 9a38d639d69..1ea594d280c 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -73,6 +73,7 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Notifications](notifications.md) - [Header File Structure](header_file_structure.md) +- [Manpages](manpages.md) ## Delayed diff --git a/doc/decisions/TEMPLATE.md b/doc/decisions/TEMPLATE.md index eea349c789b..ce5c1e95a79 100644 --- a/doc/decisions/TEMPLATE.md +++ b/doc/decisions/TEMPLATE.md @@ -4,15 +4,15 @@ ## Constraints -- -- -- +1. +2. +3. ## Assumptions -- -- -- +1. +2. +3. ## Considered Alternatives diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md new file mode 100644 index 00000000000..654bcc6c487 --- /dev/null +++ b/doc/decisions/manpages.md @@ -0,0 +1,40 @@ +# Manpages + +## Problem + +Our manpages are written as markdown in doc/help and then converted to roff and stored in doc/man. +Storing generated files is annoying, as it requires: + +- developers to always update generated files if the sources are changed +- developers not committing irrelevant changes to generated files (e.g. as may occur with different CMAKE_INSTALL_PREFIX etc.) +- require extra effort for continuous integration, e.g. [#4542](https://issues.libelektra.org/4542) + +## Constraints + +1. we want beautiful rendered man pages +2. we cannot require rare tools for the build process + +## Assumptions + +- ronn-ng doesn't have packages on any distribution (violates constraint 2.) + +## Considered Alternatives + +1. Doxygen: need to be rechecked in the latest version, see [#4551](https://issues.libelektra.org/4551) +2. Pandoc 2.9 doesn't have the Markdown description-list feature like ronn-ng has (violates constraint 1.) + +## Decision + +## Rationale + +## Implications + +## Related Decisions + +- []() +- []() +- []() + +## Notes + +Currently no solution found, please recheck assumptions and/or check out new tools. From 29f164c6da56ed7d55651becbce8cf55f2110173 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 13 Oct 2022 12:51:05 +0200 Subject: [PATCH 26/27] decisions: fix spelling --- doc/decisions/manpages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index 654bcc6c487..69a09c71c65 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -2,7 +2,7 @@ ## Problem -Our manpages are written as markdown in doc/help and then converted to roff and stored in doc/man. +Our manpages are written as Markdown in doc/help and then converted to roff and stored in doc/man. Storing generated files is annoying, as it requires: - developers to always update generated files if the sources are changed From 06a6028402d854b1f68cf8800a48afed02773272 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 13 Oct 2022 20:37:35 +0200 Subject: [PATCH 27/27] decisions: Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mihael Pranjić --- doc/decisions/EXPLANATIONS.md | 5 ++--- doc/decisions/decision_process.md | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 3e3fc72cc2c..37393a0add2 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -25,9 +25,8 @@ List all constraints given by: ## Assumptions -Often we are quite blind and do not see assumptions we have. -So this section needs special care and honesty. -Assumptions is what we believe to be true but do not or cannot really know, e.g.: +Assumptions are often overlooked, so this section needs special care and honesty. +Assumptions are what we believe to be true but do not or cannot really know, e.g.: - what users will accept - perceived usability diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index f6a94943f1f..5b07db7c852 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -2,8 +2,8 @@ ## Problem -Simply discussing in an issue and then doing an implementation is okay for non-substantial changes. -But substantial decisions must be made in a transparent and participative way. +Simply discussing in an issue and then implementing a solution is okay for non-substantial changes. +Substantial decisions must be made in a transparent and participative way. ## Constraints