Merge pull request #4528 from markus2330/master

document decision process

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)

doc/decisions/EXPLANATIONS.md

@@ -0,0 +1,92 @@
+# 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
+
+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
+- 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 not break any 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:
+  - 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:
+
+- 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
+- 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.
+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.

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.
+Before you write your first decision, read [Decision Process](decision_process.md).
 
 ## Implemented
 
@@ -44,7 +34,7 @@ section here.
 - [Memory Layout](memory_layout.md)
 - [Backend Plugin](backend_plugin.md)
 
-## Mostly Implemented
+## Partially Implemented
 
 - [Hooks](hooks.md) (@atmaxinger)
 - [Array for Warnings](warning_array.md)
@@ -77,11 +67,13 @@ section here.
 - [Error Handling](error_handling.md)
 - [Spec Expressiveness](spec_expressiveness.md)
 - [Metadata in Spec Namespace](spec_metadata.md)
+- [Decision Process](decision_process.md).
 
 ## Drafts
 
 - [Notifications](notifications.md)
 - [Header File Structure](header_file_structure.md)
+- [Manpages](manpages.md)
 
 ## Delayed
 
@@ -96,3 +88,10 @@ section here.
 - [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)

doc/decisions/template.md → doc/decisions/TEMPLATE.md

@@ -1,19 +1,39 @@
-# Template
+# TEMPLATE
 
 ## Problem
 
 ## Constraints
 
+1.
+2.
+3.
+
 ## Assumptions
 
+1.
+2.
+3.
+
 ## Considered Alternatives
 
+1.
+2.
+3.
+
 ## Decision
 
 ## Rationale
 
 ## Implications
 
+-
+-
+-
+
 ## Related Decisions
 
+- []()
+- []()
+- []()
+
 ## Notes

doc/decisions/decision_process.md

@@ -0,0 +1,151 @@
+# Decision Process
+
+## 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.
+
+## 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.
+- 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. 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:
+  - 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.
+
+## 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.
+  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 writer's mind beforehand.
+  Instead the decision process is a supported learning process.
+
+## 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 be decided upon using the decision process described here
+
+We base our decision process and template on:
+
+- [''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).
+
+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, 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)
+
+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.
+- Now it is allowed to have the decision from the previous round in the "Decision" section.
+
+### Decided
+
+- decision, rationale and implication are now filled out and fixed according to the reviews
+- decisions of this status usually already have an implementation PR
+
+### 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.
+
+- 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).
+These decision PRs are also merged for documentation purposes.
+
+## Rationale
+
+- The process is lightweight and simple.
+- 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.
+- 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
+
+- Proposal issues are obsolete.
+- The decision process creates at least:
+  - two chances to comment decisions, and
+  - two commits in the git history.
+
+## Related Decisions
+
+## 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

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.