From 650732aedf4d354ed5d59d0568980abfee1d2919 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 16 Oct 2022 18:26:59 +0200 Subject: [PATCH 01/40] decisions: decide process, improve manpages --- .github/PULL_REQUEST_TEMPLATE.md | 5 ++-- doc/decisions/README.md | 2 +- doc/decisions/decision_process.md | 23 ++++++++-------- doc/decisions/manpages.md | 39 ++++++++++++++++++++++----- doc/news/_preparation_next_release.md | 3 +++ 5 files changed, 52 insertions(+), 20 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d9f54e24ed4..d38002161a3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -38,8 +38,9 @@ need to be checked. - [ ] I added unit tests for my code - [ ] I fully described what my PR does in the documentation (not in the PR description) -- [ ] I fixed all affected documentation (see [Documentation Guidelines](https://master.libelektra.org/doc/contrib/documentation.md)) -- [ ] I added code comments, logging, and assertions as appropriate (see [Coding Guidelines](https://master.libelektra.org/doc/CODING.md)) +- [ ] I fixed all affected documentation (see [Documentation Guidelines](https://www.libelektra.org/devgettingstarted/documentation)) +- [ ] I fixed all affected decisions (see [Decision Process](https://www.libelektra.org/decisions/decision-process)) +- [ ] I added code comments, logging, and assertions as appropriate (see [Coding Guidelines](https://www.libelektra.org/devgettingstarted/coding)) - [ ] I updated all meta data (e.g. README.md of plugins and [METADATA.ini](https://master.libelektra.org/doc/METADATA.ini)) - [ ] I mentioned [every code](/.reuse/dep5) not directly written by me in [reuse syntax](https://reuse.software/) diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 12d209ddd0e..9fb8b73b0da 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -44,6 +44,7 @@ Before you write your first decision, read [Decision Process](decision_process.m ## Decided +- [Decision Process](decision_process.md) - [Capabilities](capabilities.md) - [Make elektraMalloc et al. private](elektra_malloc.md) - [Elektra Prefix](elektra_prefix.md) @@ -68,7 +69,6 @@ Before you write your first decision, read [Decision Process](decision_process.m - [Error Handling](error_handling.md) - [Spec Expressiveness](spec_expressiveness.md) - [Metadata in Spec Namespace](spec_metadata.md) -- [Decision Process](decision_process.md). ## Drafts diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 5b07db7c852..4b956908239 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -3,14 +3,14 @@ ## Problem 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. +Substantial decisions, however, must be made in a 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. -- [Documentation guidelines](/doc/contrib/documentation.md) apply. +- At least two people need to approve the decision in each round. +- [Documentation guidelines](https://www.libelektra.org/devgettingstarted/documentation) 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: @@ -24,13 +24,13 @@ Substantial decisions must be made in a transparent and participative way. - 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 questions 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 vaguely related sentences in the review. ## 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). + In general people 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. @@ -42,6 +42,9 @@ Substantial decisions must be made in a transparent and participative way. ## Considered Alternatives - Issues like https://issues.libelektra.org/4521 +- GitHub discussions +- Voting in Meetings +- The maintainer decides - PEPs: https://peps.python.org - RFCs: https://www.ietf.org/standards/rfcs/ - Change requests: https://en.wikipedia.org/wiki/Change_request @@ -76,7 +79,7 @@ The first step is to create a PR with: ### In Discussion -This step is mandatory. +> This step is mandatory. Here you must ensure: @@ -89,8 +92,6 @@ Here you must ensure: 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. - ### In Progress - You must include all further alternative proposals made in the "Considered Alternatives" section. @@ -98,6 +99,8 @@ This step is finished when every reviewer approves. ### Decided +> This step is recommended. + - decision, rationale and implication are now filled out and fixed according to the reviews - decisions of this status usually already have an implementation PR @@ -110,14 +113,12 @@ The "Implication" must clearly say how much of the decision is already implement ### Implemented -This step is mandatory. +> 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. -This step is finished when every reviewer approves. - ### Rejected Alternatively, decisions might be rejected (i.e. status quo wins). diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index 69a09c71c65..c86b62d96cc 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -8,20 +8,22 @@ 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) +- ronn-ng, which doesn't have packages on most distribution (violates constraint 2.) ## Constraints -1. we want beautiful rendered man pages +1. we want beautiful rendered man pages, e.g., OPTIONS section looks like normal 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.) +1. Write a tool that converts our specification, similar to [pythongen](src/tools/pythongen/template/template.man) +2. Write a tool that parses our `--help` output +3. [help2man](https://www.gnu.org/software/help2man/) +4. Doxygen: will be rechecked in the latest version, see [#4551](https://issues.libelektra.org/4551) +5. Pandoc 2.9: doesn't have the Markdown description-list feature¹ like ronn-ng has (violates constraint 1.) ## Decision @@ -37,4 +39,29 @@ Storing generated files is annoying, as it requires: ## Notes -Currently no solution found, please recheck assumptions and/or check out new tools. +Currently no solution found, we recheck assumptions and/or check out new tools. + +¹ronn-ng description-list feature converts: + +``` +- `-H`, `--help`: + Show the man page. +- `-V`, `--version`: + Print version info. +- `-p`, `--profile `: + Use a different kdb profile. +``` + +to: + +``` +OPTIONS + -H, --help + Show the man page. + + -V, --version + Print version info. + + -p, --profile + Use a different kdb profile. +``` diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md index c5ba3ae1e07..8f45ad9ce9d 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -279,6 +279,9 @@ This section keeps you up-to-date with the multi-language support provided by El - Documented [decision process](/doc/decisions/decision_process.md) _(Markus Raab)_ - Decided future [library split](../decisions/library_split.md) _(@kodebach)_ +- decided [decision process](https://www.libelektra.org/decisions/decision-process) _(Markus Raab)_ +- draft for [manpages](/doc/decisions/manpages.md) _(Markus Raab)_ +- <> - <> - <> - <> From 18afe2a28c4d240cd9b920414303d074482ceebb Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 16 Oct 2022 18:46:52 +0200 Subject: [PATCH 02/40] decisions: update according #4551 --- doc/decisions/manpages.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index c86b62d96cc..289cd4f6b89 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -8,7 +8,6 @@ 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) -- ronn-ng, which doesn't have packages on most distribution (violates constraint 2.) ## Constraints @@ -19,11 +18,15 @@ Storing generated files is annoying, as it requires: ## Considered Alternatives +0. ronn-ng, which doesn't have packages on most distribution (violates constraint 2.) and thus created this problem 1. Write a tool that converts our specification, similar to [pythongen](src/tools/pythongen/template/template.man) 2. Write a tool that parses our `--help` output 3. [help2man](https://www.gnu.org/software/help2man/) -4. Doxygen: will be rechecked in the latest version, see [#4551](https://issues.libelektra.org/4551) -5. Pandoc 2.9: doesn't have the Markdown description-list feature¹ like ronn-ng has (violates constraint 1.) +4. Doxygen: + - doesn't have definition lists +5. Pandoc: has quite a few dependencies and would need rewrite of the current documentation in doc/help: + - definition lists via https://pandoc.org/MANUAL.html#definition-lists + - would need YAML metadata for every file ## Decision @@ -39,9 +42,7 @@ Storing generated files is annoying, as it requires: ## Notes -Currently no solution found, we recheck assumptions and/or check out new tools. - -¹ronn-ng description-list feature converts: +ronn-ng definition lists feature converts: ``` - `-H`, `--help`: From 38ec8217c63fc8f439255fc2f75b293c5338a16b Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 16 Oct 2022 18:51:10 +0200 Subject: [PATCH 03/40] decisions: fix link --- 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 289cd4f6b89..9568f334f41 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -19,7 +19,7 @@ Storing generated files is annoying, as it requires: ## Considered Alternatives 0. ronn-ng, which doesn't have packages on most distribution (violates constraint 2.) and thus created this problem -1. Write a tool that converts our specification, similar to [pythongen](src/tools/pythongen/template/template.man) +1. Write a tool that converts our specification, similar to [pythongen](/src/tools/pythongen/template/template.man) 2. Write a tool that parses our `--help` output 3. [help2man](https://www.gnu.org/software/help2man/) 4. Doxygen: From 1c950a25db1cf871434c1ea142b82479384ac51b Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Tue, 18 Oct 2022 09:58:38 +0200 Subject: [PATCH 04/40] decisions: corrections from #4551 --- doc/decisions/manpages.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index 9568f334f41..242ce14ef89 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -3,6 +3,7 @@ ## Problem Our manpages are written as Markdown in doc/help and then converted to roff and stored in doc/man. +This was a workaround, because `ronn-ng` isn't available on most distributions and we want to avoid packages without manpages are being built. Storing generated files is annoying, as it requires: - developers to always update generated files if the sources are changed @@ -11,22 +12,23 @@ Storing generated files is annoying, as it requires: ## Constraints -1. we want beautiful rendered man pages, e.g., OPTIONS section looks like normal man pages -2. we cannot require rare tools for the build process +1. we want beautiful rendered manpages, e.g., OPTIONS section looks like normal manpages, see in Notes¹ below +2. we cannot require rare tools for the build process: the manpages must be present in every package ## Assumptions ## Considered Alternatives -0. ronn-ng, which doesn't have packages on most distribution (violates constraint 2.) and thus created this problem +0. `ronn-ng`, which doesn't have packages on most distribution (violates constraint 2.) and thus created this problem 1. Write a tool that converts our specification, similar to [pythongen](/src/tools/pythongen/template/template.man) -2. Write a tool that parses our `--help` output +2. Write a tool that parses gopts `--help` output 3. [help2man](https://www.gnu.org/software/help2man/) 4. Doxygen: - - doesn't have definition lists + - Constraint 1 probably broken 5. Pandoc: has quite a few dependencies and would need rewrite of the current documentation in doc/help: - - definition lists via https://pandoc.org/MANUAL.html#definition-lists + - Constraint 1 fulfilled via https://pandoc.org/MANUAL.html#definition-lists - would need YAML metadata for every file + (it is possible to also pass this as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system) ## Decision @@ -42,7 +44,7 @@ Storing generated files is annoying, as it requires: ## Notes -ronn-ng definition lists feature converts: +¹ ronn-ng converts: ``` - `-H`, `--help`: From 63889b69eeeda515a26930e025a303e455d7ea9f Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 11:49:33 +0200 Subject: [PATCH 05/40] decisions: describing PRs --- doc/decisions/decision_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 4b956908239..09912c7cd1c 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -25,6 +25,8 @@ Substantial decisions, however, must be made in a transparent and participative - For reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. +- Decision PRs do not significantly change anything but one decision to make discussions clearly structured. +- Changes not changing the decision step or the direction of the decision are not decision PRs. ## Assumptions From aec620f785ca38f1bdf0c954db9aaf59ed8a6c8a Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 11:54:55 +0200 Subject: [PATCH 06/40] small clarifications about pandoc --- doc/decisions/manpages.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index 242ce14ef89..7ef03926388 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -25,10 +25,12 @@ Storing generated files is annoying, as it requires: 3. [help2man](https://www.gnu.org/software/help2man/) 4. Doxygen: - Constraint 1 probably broken -5. Pandoc: has quite a few dependencies and would need rewrite of the current documentation in doc/help: - - Constraint 1 fulfilled via https://pandoc.org/MANUAL.html#definition-lists - - would need YAML metadata for every file - (it is possible to also pass this as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system) +5. Pandoc: + - has a few standard dependencies + - would need rewrite of the current documentation in doc/help: + - To fulfill Constraint 1 [https://pandoc.org/MANUAL.html#definition-lists](definition lists) would be needed + - would need YAML metadata/front matter for every file + (it is possible to also pass this as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system) ## Decision From 5ee82b09cdd64a4192cb2daf6e128cc046aaae46 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 12:00:33 +0200 Subject: [PATCH 07/40] decision: further possibilities --- doc/decisions/manpages.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/decisions/manpages.md b/doc/decisions/manpages.md index 7ef03926388..4ddfc39cb46 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/manpages.md @@ -30,7 +30,9 @@ Storing generated files is annoying, as it requires: - would need rewrite of the current documentation in doc/help: - To fulfill Constraint 1 [https://pandoc.org/MANUAL.html#definition-lists](definition lists) would be needed - would need YAML metadata/front matter for every file - (it is possible to also pass this as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system) + (It would be possible, but not advisable, to: + - also pass information as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system + - that we use the current (non-standard) front matter and convert it to Pandoc's frontmatter but this makes the build system more complicated) ## Decision From 7e8f42fa8d7e2018bafb4aef4a288ae83655ac66 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 12:04:23 +0200 Subject: [PATCH 08/40] decisions: fix spelling of man pages see #4567 --- doc/decisions/README.md | 2 +- doc/decisions/{manpages.md => man_pages.md} | 14 ++++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) rename doc/decisions/{manpages.md => man_pages.md} (76%) diff --git a/doc/decisions/README.md b/doc/decisions/README.md index 9fb8b73b0da..76629681cb1 100644 --- a/doc/decisions/README.md +++ b/doc/decisions/README.md @@ -74,7 +74,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) +- [Man Pages](man_pages.md) ## Delayed diff --git a/doc/decisions/manpages.md b/doc/decisions/man_pages.md similarity index 76% rename from doc/decisions/manpages.md rename to doc/decisions/man_pages.md index 4ddfc39cb46..4475c24ba09 100644 --- a/doc/decisions/manpages.md +++ b/doc/decisions/man_pages.md @@ -1,9 +1,9 @@ -# Manpages +# Man Pages ## Problem -Our manpages are written as Markdown in doc/help and then converted to roff and stored in doc/man. -This was a workaround, because `ronn-ng` isn't available on most distributions and we want to avoid packages without manpages are being built. +Our man pages are written as Markdown in doc/help and then converted to roff and stored in doc/man. +This was a workaround, because `ronn-ng` isn't available on most distributions and we want to avoid packages without man pages are being built. Storing generated files is annoying, as it requires: - developers to always update generated files if the sources are changed @@ -12,8 +12,8 @@ Storing generated files is annoying, as it requires: ## Constraints -1. we want beautiful rendered manpages, e.g., OPTIONS section looks like normal manpages, see in Notes¹ below -2. we cannot require rare tools for the build process: the manpages must be present in every package +1. we want beautiful rendered man pages, e.g., OPTIONS section looks like normal man pages, see in Notes¹ below +2. we cannot require rare tools for the build process: the man pages must be present in every package ## Assumptions @@ -31,11 +31,13 @@ Storing generated files is annoying, as it requires: - To fulfill Constraint 1 [https://pandoc.org/MANUAL.html#definition-lists](definition lists) would be needed - would need YAML metadata/front matter for every file (It would be possible, but not advisable, to: - - also pass information as command-line arguments via `--variable` but then we would move meta-information about manpages to the build system + - also pass information as command-line arguments via `--variable` but then we would move meta-information about man pages to the build system - that we use the current (non-standard) front matter and convert it to Pandoc's frontmatter but this makes the build system more complicated) ## Decision +Not yet done except spelling of man pages, see [#4567](https://issues.libelektra.org/4567). + ## Rationale ## Implications From 73533ce46b5e28871e5f4d44532caf71fcfaa4a8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 18:29:55 +0200 Subject: [PATCH 09/40] decisions: reformat --- doc/decisions/man_pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/decisions/man_pages.md b/doc/decisions/man_pages.md index 4475c24ba09..479077c2091 100644 --- a/doc/decisions/man_pages.md +++ b/doc/decisions/man_pages.md @@ -31,8 +31,8 @@ Storing generated files is annoying, as it requires: - To fulfill Constraint 1 [https://pandoc.org/MANUAL.html#definition-lists](definition lists) would be needed - would need YAML metadata/front matter for every file (It would be possible, but not advisable, to: - - also pass information as command-line arguments via `--variable` but then we would move meta-information about man pages to the build system - - that we use the current (non-standard) front matter and convert it to Pandoc's frontmatter but this makes the build system more complicated) + - also pass information as command-line arguments via `--variable` but then we would move meta-information about man pages to the build system + - that we use the current (non-standard) front matter and convert it to Pandoc's frontmatter but this makes the build system more complicated) ## Decision From c48aac8d41bd010cba8df9d1e65f20ff70d63593 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 20 Oct 2022 20:25:49 +0200 Subject: [PATCH 10/40] news: fix link --- 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 8f45ad9ce9d..51b25bf023d 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -280,7 +280,7 @@ This section keeps you up-to-date with the multi-language support provided by El - Documented [decision process](/doc/decisions/decision_process.md) _(Markus Raab)_ - Decided future [library split](../decisions/library_split.md) _(@kodebach)_ - decided [decision process](https://www.libelektra.org/decisions/decision-process) _(Markus Raab)_ -- draft for [manpages](/doc/decisions/manpages.md) _(Markus Raab)_ +- draft for [man pages](/doc/decisions/man_pages.md) _(Markus Raab)_ - <> - <> - <> From 3b06a4e75ebc477214bf96decc54a68c293ab25e Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 21 Oct 2022 20:57:22 +0200 Subject: [PATCH 11/40] decisions: fix broken link --- doc/decisions/man_pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/man_pages.md b/doc/decisions/man_pages.md index 479077c2091..f710e20eac9 100644 --- a/doc/decisions/man_pages.md +++ b/doc/decisions/man_pages.md @@ -28,7 +28,7 @@ Storing generated files is annoying, as it requires: 5. Pandoc: - has a few standard dependencies - would need rewrite of the current documentation in doc/help: - - To fulfill Constraint 1 [https://pandoc.org/MANUAL.html#definition-lists](definition lists) would be needed + - To fulfill Constraint 1 [definition lists](https://pandoc.org/MANUAL.html#definition-lists) would be needed - would need YAML metadata/front matter for every file (It would be possible, but not advisable, to: - also pass information as command-line arguments via `--variable` but then we would move meta-information about man pages to the build system From 7de209ebfcba885059b4969b2fecd39fca4ee300 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 21 Oct 2022 21:02:16 +0200 Subject: [PATCH 12/40] decision: write about who is allowed to merge --- 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 09912c7cd1c..1b3f01b4adc 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -27,6 +27,7 @@ Substantial decisions, however, must be made in a transparent and participative - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. - Decision PRs do not significantly change anything but one decision to make discussions clearly structured. - Changes not changing the decision step or the direction of the decision are not decision PRs. +- The person merging the decision PR must be someone else as the person that created the decision. ## Assumptions From 0c980ad0b10443c4f28a1be2ef89a30f29946af4 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Thu, 27 Oct 2022 11:48:30 +0200 Subject: [PATCH 13/40] decisions: add clarifications/improvements --- doc/decisions/EXPLANATIONS.md | 5 +++++ doc/decisions/TEMPLATE.md | 8 +++++--- doc/decisions/decision_process.md | 6 ++++++ 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 37393a0add2..08aefef3c81 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -83,10 +83,15 @@ This can be: This section has links to other decisions with description what the relation is. Decisions that give constraints must be listed in "Constraints" above. +> Note: +> Sometimes the best solution is only understood if the relation between decisions becomes clear. + ## 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. +Any discarded ideas and opinions that are not complete enough to be a "Considered Alternatives" can be written here. + Furthermore, the author, acknowledgements, dates etc. can be written here. diff --git a/doc/decisions/TEMPLATE.md b/doc/decisions/TEMPLATE.md index ce5c1e95a79..5509ca95c4f 100644 --- a/doc/decisions/TEMPLATE.md +++ b/doc/decisions/TEMPLATE.md @@ -16,9 +16,11 @@ ## Considered Alternatives -1. -2. -3. +### Alternative A + +### Alternative B + +### Alternative C ## Decision diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 1b3f01b4adc..7c94e0023b5 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -5,6 +5,8 @@ Simply discussing in an issue and then implementing a solution is okay for non-substantial changes. Substantial decisions, however, must be made in a transparent and participative way. +The main purpose of the decision process is to get a common understanding of the problems and the impacts of possible solutions. + ## Constraints - All relevant information about decisions must be within Elektra's repository. @@ -70,6 +72,8 @@ We base our decision process and template on: Following subsections describe all steps a decision might run through. Only two of them are mandatory. +In all steps we avoid discussions in issues or PRs but directly update the decision text with the different opinions and discuss the text of the decision PR. + We use the template [TEMPLATE.md](TEMPLATE.md). Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). @@ -80,6 +84,8 @@ The first step is to create a PR with: - **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. +> At least the problem must be clear to everyone involved before the decision can leave the "Drafts" status. + ### In Discussion > This step is mandatory. From b26bc2e342246372c192f7fea8f274d1997f35c3 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 12:38:25 +0200 Subject: [PATCH 14/40] decisions: rephrase+add example --- doc/decisions/EXPLANATIONS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 08aefef3c81..4047718c456 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -92,6 +92,7 @@ Here is a full list of off-line discussions, issue trackers, PRs etc. related to 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. -Any discarded ideas and opinions that are not complete enough to be a "Considered Alternatives" can be written here. +Any discarded, incomplete and unexplored ideas/opinions, which are not complete enough to be "Considered Alternatives", can be written here. +For example, if it is obvious that the idea does not even solve the problem. Furthermore, the author, acknowledgements, dates etc. can be written here. From 77a90b01bc2aee827391520c6a2c5824f06ff1e5 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 12:52:24 +0200 Subject: [PATCH 15/40] decisions: clarify importance of decision text --- doc/decisions/decision_process.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 7c94e0023b5..5a2654d7450 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -72,7 +72,8 @@ We base our decision process and template on: Following subsections describe all steps a decision might run through. Only two of them are mandatory. -In all steps we avoid discussions in issues or PRs but directly update the decision text with the different opinions and discuss the text of the decision PR. +In all steps we directly update the decision text with the different opinions. +Discussions should focus on the decision text so that the text evolves with the opinions. We use the template [TEMPLATE.md](TEMPLATE.md). Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). @@ -142,6 +143,10 @@ These decision PRs are also merged for documentation purposes. - 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. +- The decision process is focused around the decision text (and not forum-like discussions), so that: + - The resulting text is understandable without reading any discussions. + - There is a common understanding after only reading the decision text. + - To avoid any gaps of reading discussions and the decision. ## Implications @@ -154,7 +159,7 @@ These decision PRs are also merged for documentation purposes. ## Notes -- Early discussions in issues or in discussions is not prohibited. +- Discussions in issues/discussions are 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. From bdb29bab5140c8ad406acdf1465f82b5776ab354 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 13:22:02 +0200 Subject: [PATCH 16/40] decisions: clarify sentence by removing rationale --- doc/decisions/decision_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 5a2654d7450..dea534e02e8 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -27,7 +27,7 @@ The main purpose of the decision process is to get a common understanding of the - For reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. -- Decision PRs do not significantly change anything but one decision to make discussions clearly structured. +- Decision PRs do not significantly change anything but one decision. - Changes not changing the decision step or the direction of the decision are not decision PRs. - The person merging the decision PR must be someone else as the person that created the decision. From 1c8d75fd5f665d3ba4f56e5c0827716c44db6d0b Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:12:12 +0200 Subject: [PATCH 17/40] decisions: add major constraints&assumptions --- doc/decisions/decision_process.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index dea534e02e8..0e62781f5a7 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -30,6 +30,15 @@ The main purpose of the decision process is to get a common understanding of the - Decision PRs do not significantly change anything but one decision. - Changes not changing the decision step or the direction of the decision are not decision PRs. - The person merging the decision PR must be someone else as the person that created the decision. +- The purpose of decisions is to have clear descriptions of technical problems and solutions. + There is no claim that decisions contain everything that was said. + In particular corrections of wrong decision text is, if at all, only visible via git history. + Rather it is important that decisions: + - contain everything relevant, and + - what is written is technically correct. +- Participants are explicitly allowed to skip discussions and only read the decisions text. + If the problem is not yet clear, only partial reviews are encouraged. + @markus2330 will do so of time budget reasons and to make sure the decisions stay understandable. ## Assumptions @@ -43,6 +52,7 @@ The main purpose of the decision process is to get a common understanding of the - 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 writer's mind beforehand. Instead the decision process is a supported learning process. +- People focus on getting the best solutions and not to wish for the impossible. ## Considered Alternatives From 16e7d613bee15f3a33622164bcd7e11b875e70c3 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:37:20 +0200 Subject: [PATCH 18/40] decisions: clarify relations --- doc/decisions/EXPLANATIONS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 4047718c456..2802677948d 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -81,10 +81,12 @@ This can be: ## Related Decisions This section has links to other decisions with description what the relation is. +One-side relations are allowed, not every decision must link back. Decisions that give constraints must be listed in "Constraints" above. > Note: > Sometimes the best solution is only understood if the relation between decisions becomes clear. +> Make sure that everything that requires updates to a decision, is listed as "Constraints" or "Assumptions". ## Notes From 2e10d4b225fccb02bdb81e700efec6449354e638 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:48:16 +0200 Subject: [PATCH 19/40] decisions: clarify consensus --- 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 0e62781f5a7..c75f056d43f 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -44,8 +44,8 @@ The main purpose of the decision process is to get a common understanding of the - 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 people 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. + In general people want change if it brings Elektra towards its [goals](/doc/GOALS.md). +- We will always be able to reach an consensus even if it requires that the core or plugins get multiple implementations. 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. @@ -53,6 +53,8 @@ The main purpose of the decision process is to get a common understanding of the 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. - People focus on getting the best solutions and not to wish for the impossible. +- After 1.0, due to stability guarantees, not so many decisions are required anymore. + People are free to reimplement the libraries or plugins of Elektra if they disagree with Elektra's [quality goals](/doc/GOALS.md) and still help with our vision. ## Considered Alternatives @@ -173,4 +175,5 @@ These decision PRs are also merged for documentation purposes. 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 +Written by Markus Raab 10.10.2022. +Second discussion round 28.10.2022. From 14b9ef015d08a320ed700744eecfc0b8c0c4e935 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:50:22 +0200 Subject: [PATCH 20/40] Update doc/decisions/decision_process.md Co-authored-by: Florian Lindner --- doc/decisions/decision_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index c75f056d43f..291422ea7cb 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -60,7 +60,7 @@ The main purpose of the decision process is to get a common understanding of the - Issues like https://issues.libelektra.org/4521 - GitHub discussions -- Voting in Meetings +- Votings - The maintainer decides - PEPs: https://peps.python.org - RFCs: https://www.ietf.org/standards/rfcs/ From fd40905dae8bb7581268dc1d75e844df000c04cf Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:51:03 +0200 Subject: [PATCH 21/40] Update doc/decisions/decision_process.md 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/decision_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 291422ea7cb..1f260d7af16 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -12,7 +12,7 @@ The main purpose of the decision process is to get a common understanding of the - 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 approve the decision in each round. -- [Documentation guidelines](https://www.libelektra.org/devgettingstarted/documentation) apply. +- [Documentation guidelines](../contrib/documentation) 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: From 679609185c68de4d87245ae0e408d5b72af11b7d Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 14:58:43 +0200 Subject: [PATCH 22/40] decisions: clarify rationale for notes --- doc/decisions/EXPLANATIONS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 2802677948d..56158ac81e2 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -96,5 +96,6 @@ If particular information is important and not present in any sections above, pl Any discarded, incomplete and unexplored ideas/opinions, which are not complete enough to be "Considered Alternatives", can be written here. For example, if it is obvious that the idea does not even solve the problem. +Unlike the main decisions and considered alternatives text in the notes does not need rationale. Furthermore, the author, acknowledgements, dates etc. can be written here. From cb5b9129a68f0302894ed500a6c6bb1dbf11ad59 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Fri, 28 Oct 2022 15:06:00 +0200 Subject: [PATCH 23/40] decisions: add assumption --- doc/decisions/decision_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 1f260d7af16..b7d673ffc7a 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -53,6 +53,8 @@ The main purpose of the decision process is to get a common understanding of the 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. - People focus on getting the best solutions and not to wish for the impossible. +- People creating decision PRs have strong motives to also finish it. + They take extra effort on them to be clear about the problem and find the best solution. - After 1.0, due to stability guarantees, not so many decisions are required anymore. People are free to reimplement the libraries or plugins of Elektra if they disagree with Elektra's [quality goals](/doc/GOALS.md) and still help with our vision. From f86628ce541a2a451eca393a758d083a643e0a59 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 07:29:17 +0100 Subject: [PATCH 24/40] decisions: clarify problem --- doc/decisions/man_pages.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/decisions/man_pages.md b/doc/decisions/man_pages.md index f710e20eac9..72e335c4761 100644 --- a/doc/decisions/man_pages.md +++ b/doc/decisions/man_pages.md @@ -2,14 +2,23 @@ ## Problem -Our man pages are written as Markdown in doc/help and then converted to roff and stored in doc/man. -This was a workaround, because `ronn-ng` isn't available on most distributions and we want to avoid packages without man pages are being built. -Storing generated files is annoying, as it requires: +Our man pages are written as Markdown in `doc/help` and then converted to roff and stored in `doc/man`. +These are the only generated files in our version control system. +Having such files is a problematic workaround, which was introduced because `ronn-ng` is not available on most distributions. +The poor availability of the package `ronn-ng` is a problem because distributions usually build packages by exclusively relying on other packages of the distribution. +E.g. `dpkg-buildpackage` must work with only `deb` packages installed (and not any packages via `gem`). + +We have a mechanism to automatically disable (re)building man pages. +But we want to avoid that distributions build packages without man pages, hence we added the generated files. + +Storing generated files, however, is problematic, 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.) +- 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) +TODO: everything below is draft, please don't comment on it. + ## Constraints 1. we want beautiful rendered man pages, e.g., OPTIONS section looks like normal man pages, see in Notes¹ below From b5baca12a0ca875d518cd1d684654e92049d5ac8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 07:41:02 +0100 Subject: [PATCH 25/40] decisions: clarify problem of version --- doc/decisions/man_pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/man_pages.md b/doc/decisions/man_pages.md index 72e335c4761..1746655550b 100644 --- a/doc/decisions/man_pages.md +++ b/doc/decisions/man_pages.md @@ -6,7 +6,7 @@ Our man pages are written as Markdown in `doc/help` and then converted to roff a These are the only generated files in our version control system. Having such files is a problematic workaround, which was introduced because `ronn-ng` is not available on most distributions. The poor availability of the package `ronn-ng` is a problem because distributions usually build packages by exclusively relying on other packages of the distribution. -E.g. `dpkg-buildpackage` must work with only `deb` packages installed (and not any packages via `gem`). +E.g. `dpkg-buildpackage` must work with only `deb` packages installed (and not any packages via `gem`, as would be needed to get `ronn-ng v0.10.1`). We have a mechanism to automatically disable (re)building man pages. But we want to avoid that distributions build packages without man pages, hence we added the generated files. From 8b64c3e8e4126d961f7a3f96f2277f9c10a75317 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 07:52:41 +0100 Subject: [PATCH 26/40] Apply suggestions from @kodebach 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/decision_process.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index b7d673ffc7a..bb4483f9861 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -27,18 +27,20 @@ The main purpose of the decision process is to get a common understanding of the - For reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. -- Decision PRs do not significantly change anything but one decision. +- Decision PRs only contain a single decision and changes directly related to the decision. (e.g. adding it as a "Related Decision" elsewhere) - Changes not changing the decision step or the direction of the decision are not decision PRs. -- The person merging the decision PR must be someone else as the person that created the decision. +- The person merging the decision PR must be someone other than the person that created the decision. - The purpose of decisions is to have clear descriptions of technical problems and solutions. There is no claim that decisions contain everything that was said. In particular corrections of wrong decision text is, if at all, only visible via git history. Rather it is important that decisions: - contain everything relevant, and - what is written is technically correct. -- Participants are explicitly allowed to skip discussions and only read the decisions text. - If the problem is not yet clear, only partial reviews are encouraged. - @markus2330 will do so of time budget reasons and to make sure the decisions stay understandable. +- Reviewers are only required to read the files in the PR. + They may ignore the discussions surrounding the decision. + Reviews should focus on the "Problem" section first, and only when that is agreed upon focus in the other parts. + It is encouraged that at least one reviewer provides a review _without_ participating in the discussion. + This ensures that there aren't any unintentional shared assumptions between discussion participants. ## Assumptions From 5b70006d13907b6101ff60cd4eab5ffa0f8163a8 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:01:06 +0100 Subject: [PATCH 27/40] decisions: allow backlinks --- 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 bb4483f9861..8aabbd22b08 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -7,6 +7,13 @@ Substantial decisions, however, must be made in a transparent and participative The main purpose of the decision process is to get a common understanding of the problems and the impacts of possible solutions. +## Terminology + +- `Decision`: + A text file which contains the content as [explained here](EXPLANATIONS.md). +- `Decision PR`: + A pull request that contains changes for decisions. + ## Constraints - All relevant information about decisions must be within Elektra's repository. @@ -27,7 +34,8 @@ The main purpose of the decision process is to get a common understanding of the - For reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. -- Decision PRs only contain a single decision and changes directly related to the decision. (e.g. adding it as a "Related Decision" elsewhere) +- Decision PRs only modify a *single* decision. + Small exceptions like backlinks from other decisions are okay, though. - Changes not changing the decision step or the direction of the decision are not decision PRs. - The person merging the decision PR must be someone other than the person that created the decision. - The purpose of decisions is to have clear descriptions of technical problems and solutions. From 23ba841c7c544ffd828a340465f343f9062570c2 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:05:17 +0100 Subject: [PATCH 28/40] decisions: move main purpose at one place --- doc/decisions/decision_process.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 8aabbd22b08..28f380d99b1 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -5,15 +5,18 @@ Simply discussing in an issue and then implementing a solution is okay for non-substantial changes. Substantial decisions, however, must be made in a transparent and participative way. -The main purpose of the decision process is to get a common understanding of the problems and the impacts of possible solutions. - -## Terminology +### Terminology - `Decision`: A text file which contains the content as [explained here](EXPLANATIONS.md). - `Decision PR`: A pull request that contains changes for decisions. +### Main Purpose + +- of decisions is to have clear descriptions of technical problems and solutions. +- of the decision process is to get a common understanding of the problems and the impacts of possible solutions. + ## Constraints - All relevant information about decisions must be within Elektra's repository. @@ -38,7 +41,6 @@ The main purpose of the decision process is to get a common understanding of the Small exceptions like backlinks from other decisions are okay, though. - Changes not changing the decision step or the direction of the decision are not decision PRs. - The person merging the decision PR must be someone other than the person that created the decision. -- The purpose of decisions is to have clear descriptions of technical problems and solutions. There is no claim that decisions contain everything that was said. In particular corrections of wrong decision text is, if at all, only visible via git history. Rather it is important that decisions: From 6b6687c63474a1bfbb6128d69480e5fc3a982a27 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:07:56 +0100 Subject: [PATCH 29/40] decisions: remove "discarded" --- doc/decisions/EXPLANATIONS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/decisions/EXPLANATIONS.md b/doc/decisions/EXPLANATIONS.md index 56158ac81e2..31005b60bd5 100644 --- a/doc/decisions/EXPLANATIONS.md +++ b/doc/decisions/EXPLANATIONS.md @@ -94,8 +94,8 @@ Here is a full list of off-line discussions, issue trackers, PRs etc. related to 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. -Any discarded, incomplete and unexplored ideas/opinions, which are not complete enough to be "Considered Alternatives", can be written here. +Any incomplete and unexplored idea/opinion, which is not complete enough to be in "Considered Alternatives", can be written here. For example, if it is obvious that the idea does not even solve the problem. -Unlike the main decisions and considered alternatives text in the notes does not need rationale. +Unlike the main decisions and considered alternatives, text in the notes does not need rationale. Furthermore, the author, acknowledgements, dates etc. can be written here. From c1a3d5c9341d24b6391c49cf098a237485ede18c Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:24:15 +0100 Subject: [PATCH 30/40] decisions: clarify when not needed --- doc/decisions/decision_process.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 28f380d99b1..feee9b244ef 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -46,6 +46,9 @@ Substantial decisions, however, must be made in a transparent and participative Rather it is important that decisions: - contain everything relevant, and - what is written is technically correct. +- Usually no decisions are needed for libraries, plugins, tools or bindings if: + - they are similar to already existing modules (e.g. yet another checker plugin) + - if they reimplement some existing module (e.g. reimplementation in other programming languages) - Reviewers are only required to read the files in the PR. They may ignore the discussions surrounding the decision. Reviews should focus on the "Problem" section first, and only when that is agreed upon focus in the other parts. @@ -67,8 +70,6 @@ Substantial decisions, however, must be made in a transparent and participative - People focus on getting the best solutions and not to wish for the impossible. - People creating decision PRs have strong motives to also finish it. They take extra effort on them to be clear about the problem and find the best solution. -- After 1.0, due to stability guarantees, not so many decisions are required anymore. - People are free to reimplement the libraries or plugins of Elektra if they disagree with Elektra's [quality goals](/doc/GOALS.md) and still help with our vision. ## Considered Alternatives From 190cec69746f77ed9824bce3e01397076bbc1f6a Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:29:20 +0100 Subject: [PATCH 31/40] decisions: don't require "Considered Alternatives" --- 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 feee9b244ef..dfad74d628b 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -109,8 +109,9 @@ Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). The first step is to create a PR with: -- **one** decision, where at least the "Problem" and "Considered Alternatives" are filled out. +- **one** decision, where at least the "Problem" is filled out. - a link from [README.md](README.md) from the "Drafts" section to this decision. +- optional backlinks from related decisions. > At least the problem must be clear to everyone involved before the decision can leave the "Drafts" status. From e3ed16ee38c7a7de287321127df12611cd738ea7 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:43:54 +0100 Subject: [PATCH 32/40] decisions: clarify where the steps are explained --- doc/decisions/decision_process.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index dfad74d628b..057ecdf6088 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -105,15 +105,18 @@ Discussions should focus on the decision text so that the text evolves with the We use the template [TEMPLATE.md](TEMPLATE.md). Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). +We use following steps for decision PRs: + ### Drafts The first step is to create a PR with: -- **one** decision, where at least the "Problem" is filled out. +- **one** decision, where at least the "Problem" is filled out and "Decision", "Rationale" and "Implications" are **not** yet filled out. - a link from [README.md](README.md) from the "Drafts" section to this decision. - optional backlinks from related decisions. > At least the problem must be clear to everyone involved before the decision can leave the "Drafts" status. +> It must be so clear that everyone would be able to write a test case that shows if a solution fixes the problem. ### In Discussion @@ -121,14 +124,14 @@ The first step is to create a PR with: Here you must ensure: +- problem, constraint and assumptions are well-explained and sound - 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) +- "Decision", "Rationale" and "Implications" are **not** yet filled out if there are people arguing for different options -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. +Here the decision should not only have one decision but should describe several solutions. +For each solution a proposal, rationale and optionally implications should be given. ### In Progress @@ -139,7 +142,7 @@ For each solution a proposal, rationale and implication should be given. > This step is recommended. -- decision, rationale and implication are now filled out and fixed according to the reviews +- "Decision", "Rationale" and "Implications" are now filled out and fixed according to the reviews - decisions of this status usually already have an implementation PR ### Partially Implemented @@ -168,6 +171,7 @@ These decision PRs are also merged for documentation purposes. - 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). +- "Decision", "Rationale" and "Implications" are filled out later to keep the discussion unbiased - 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. From 8762b6b93a721978a71477b4b26042d52e29deea Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 08:59:04 +0100 Subject: [PATCH 33/40] decisions: clarify problem --- doc/decisions/decision_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 057ecdf6088..2ea57dcfd99 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -4,6 +4,8 @@ Simply discussing in an issue and then implementing a solution is okay for non-substantial changes. Substantial decisions, however, must be made in a transparent and participative way. +Discussing fundamental problems in forum-like threads showed to be repetitive and ineffective. +Decisions by supervisors are undemocratic and decisions in meetings are nontransparent for the outside world. ### Terminology From 32a4748ff657cf6fcf2be2c2e7d520116b2f0f3b Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 11:03:57 +0100 Subject: [PATCH 34/40] decisions: clarify that reviewers help authors --- doc/decisions/decision_process.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 2ea57dcfd99..76dab86a6a2 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -13,6 +13,10 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans A text file which contains the content as [explained here](EXPLANATIONS.md). - `Decision PR`: A pull request that contains changes for decisions. +- `Decision author`: + Is the person who creates the decision PR. +- `Decision reviewer`: + Is the person who reviews the decision PR. ### Main Purpose @@ -36,7 +40,7 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans 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: +- For decision reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. - Decision PRs only modify a *single* decision. @@ -54,14 +58,17 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans - Reviewers are only required to read the files in the PR. They may ignore the discussions surrounding the decision. Reviews should focus on the "Problem" section first, and only when that is agreed upon focus in the other parts. - It is encouraged that at least one reviewer provides a review _without_ participating in the discussion. + It is encouraged that at least one decision reviewer provides a review _without_ participating in the discussion. This ensures that there aren't any unintentional shared assumptions between discussion participants. ## 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. +- Decision authors and reviewers want Elektra to improve, so they also want to accept (acceptable) decisions. In general people want change if it brings Elektra towards its [goals](/doc/GOALS.md). +- All decision reviewers want to help the decision authors to write a good decision. +- Decision authors are the main force behind a decision and possibly also of specific solutions. + Nevertheless they don't want to avoid other solutions, are open to arguments/facts/etc. and incorporate all input of decision PR fairly. - We will always be able to reach an consensus even if it requires that the core or plugins get multiple implementations. 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. From c579b76971d237754c0bca44937792436382254e Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 11:10:14 +0100 Subject: [PATCH 35/40] decisions: write implication --- doc/decisions/decision_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 76dab86a6a2..78f207e43f1 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -195,6 +195,8 @@ These decision PRs are also merged for documentation purposes. - The decision process creates at least: - two chances to comment decisions, and - two commits in the git history. +- It might be a barrier for newcomers to write a decision. + This is considered to be okay, as topics that need a decision are not the topics for newcomers. ## Related Decisions From 538b3103de7bb7ceb078682893867841b8578758 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 11:32:24 +0100 Subject: [PATCH 36/40] decisions: fix formatting --- doc/decisions/decision_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 78f207e43f1..7669931b706 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -43,7 +43,7 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans - For decision reviewers: - Prefer to directly give suggestions how to change sentences. - General questions should be asked in the root of "Conversation" and not at vaguely related sentences in the review. -- Decision PRs only modify a *single* decision. +- Decision PRs only modify a _single_ decision. Small exceptions like backlinks from other decisions are okay, though. - Changes not changing the decision step or the direction of the decision are not decision PRs. - The person merging the decision PR must be someone other than the person that created the decision. From cb5d3116003755586f093282c46486d38d23a1a4 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 11:43:28 +0100 Subject: [PATCH 37/40] decisions: science not only opinion --- doc/decisions/decision_process.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 7669931b706..722440cf72a 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -64,6 +64,8 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans ## Assumptions - People want to be informed about or even participate in what Elektra looks like in the future. +- Decision authors have some scientific background and want decisions based on science, and not only on opinions. +- If assumptions, including this ones written here, are broken, decisions will be redone. - Decision authors and reviewers want Elektra to improve, so they also want to accept (acceptable) decisions. In general people want change if it brings Elektra towards its [goals](/doc/GOALS.md). - All decision reviewers want to help the decision authors to write a good decision. From a0d4f0fe603e2db9033d5dc7a5c5e2064c25bc46 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Sun, 30 Oct 2022 11:56:56 +0100 Subject: [PATCH 38/40] decisions: fix link --- doc/decisions/decision_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 722440cf72a..2583e76e40d 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -28,7 +28,7 @@ Decisions by supervisors are undemocratic and decisions in meetings are nontrans - 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 approve the decision in each round. -- [Documentation guidelines](../contrib/documentation) apply. +- [Documentation guidelines](../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: From c28ec36f757131a2dccd34cfde05f66ca36501b0 Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 31 Oct 2022 10:13:30 +0100 Subject: [PATCH 39/40] decisions: clarify merge on every step --- doc/decisions/decision_process.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/decisions/decision_process.md b/doc/decisions/decision_process.md index 2583e76e40d..4f5b4f895a4 100644 --- a/doc/decisions/decision_process.md +++ b/doc/decisions/decision_process.md @@ -107,16 +107,14 @@ We base our decision process and template on: - [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. - -In all steps we directly update the decision text with the different opinions. -Discussions should focus on the decision text so that the text evolves with the opinions. - We use the template [TEMPLATE.md](TEMPLATE.md). Explanations of the template are in [EXPLANATIONS.md](EXPLANATIONS.md). -We use following steps for decision PRs: +Following subsections describe all steps a decision might run through. +Each step requires two reviews and the merging of the decision PR. + +In each step we directly update the decision text with the different opinions. +Discussions should focus on the decision text so that the text evolves with the opinions. ### Drafts From 99cb07833852b9955e4690566e96f7ed404b4dab Mon Sep 17 00:00:00 2001 From: Markus Raab Date: Mon, 31 Oct 2022 10:15:21 +0100 Subject: [PATCH 40/40] decisions: update solution --- doc/decisions/man_pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/decisions/man_pages.md b/doc/decisions/man_pages.md index 1746655550b..fd3e0fa25a0 100644 --- a/doc/decisions/man_pages.md +++ b/doc/decisions/man_pages.md @@ -28,7 +28,7 @@ TODO: everything below is draft, please don't comment on it. ## Considered Alternatives -0. `ronn-ng`, which doesn't have packages on most distribution (violates constraint 2.) and thus created this problem +0. staying with `ronn-ng` but add the man pages only in the release tarballs but not to `git` 1. Write a tool that converts our specification, similar to [pythongen](/src/tools/pythongen/template/template.man) 2. Write a tool that parses gopts `--help` output 3. [help2man](https://www.gnu.org/software/help2man/)