\label{doc_decisions_3_decided_decision_process_md_md_doc_decisions_3_decided_decision_process}%
\Hypertarget{doc_decisions_3_decided_decision_process_md_md_doc_decisions_3_decided_decision_process}%
 \hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1972}{}\doxysection{Problem}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1972}
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.\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1973}{}\doxysubsection{Terminology}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1973}

\begin{DoxyItemize}
\item {\ttfamily Decision}\+: A text file which contains the content as \mbox{\hyperlink{doc_decisions_EXPLANATIONS_md}{explained here}}.
\item {\ttfamily Decision PR}\+: A pull request that contains changes for decisions.
\item {\ttfamily Decision author}\+: Is the person who creates the decision PR.
\item {\ttfamily Decision reviewer}\+: Is the person who reviews the decision PR.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1974}{}\doxysubsection{Main Purpose}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1974}

\begin{DoxyItemize}
\item of decisions is to have clear descriptions of technical problems and solutions.
\item of the decision process is to get a common understanding of the problems and the impacts of possible solutions.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1975}{}\doxysection{Constraints}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1975}

\begin{DoxyItemize}
\item All relevant information about decisions must be within Elektra\textquotesingle{}s repository.
\item All decisions must go through at least two review rounds, with a merge in between.
\item At least two people need to approve the decision in each round.
\item \mbox{\hyperlink{doc_contrib_documentation_md}{Documentation guidelines}} apply.
\item During the decision process, the PRs constantly get updated\+:
\begin{DoxyItemize}
\item Make changes as new commits to the pull request.
\item Questions in the PRs are answered by\+:
\begin{DoxyEnumerate}
\item Update the PR and incorporate the review.
\item Reply on Git\+Hub\+:
\begin{DoxyItemize}
\item Give a short summary of what you did in a single comment, and reply to individual questions if necessary.
\item Link to commit SHA-\/\+IDs for details.
\end{DoxyItemize}
\item Mark all Git\+Hub threads as resolved, if you incorporated the feedback as suggested. Committing a suggestion directly on Git\+Hub does this automatically.
\end{DoxyEnumerate}
\item As generally recommended in Elektra, do not squash commits after they are visible on the pull request.
\item Rebase only if the decision was already accepted and has a merge conflict.
\end{DoxyItemize}
\item For decision reviewers\+:
\begin{DoxyItemize}
\item Prefer to directly give suggestions how to change sentences.
\item General questions should be asked in the root of \char`\"{}\+Conversation\char`\"{} and not at vaguely related sentences in the review.
\end{DoxyItemize}
\item Decision PRs only modify a {\itshape single} decision. Small exceptions like backlinks from other decisions are okay, though.
\item Changes not changing the decision step or the direction of the decision are not decision PRs.
\item The person merging the decision PR must be someone other than the person that created the decision. 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\+:
\begin{DoxyItemize}
\item contain everything relevant, and
\item what is written is technically correct.
\end{DoxyItemize}
\item Usually no decisions are needed for libraries, plugins, tools or bindings if\+:
\begin{DoxyItemize}
\item they are similar to already existing modules (e.\+g. yet another checker plugin)
\item if they reimplement some existing module (e.\+g. reimplementation in other programming languages)
\end{DoxyItemize}
\item Reviewers are only required to read the files in the PR. They may ignore the discussions surrounding the decision. Reviews should focus on the \char`\"{}\+Problem\char`\"{} section first, and only when that is agreed upon focus in the other parts. It is encouraged that at least one decision reviewer provides a review {\itshape without} participating in the discussion. This ensures that there aren\textquotesingle{}t any unintentional shared assumptions between discussion participants.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1976}{}\doxysection{Assumptions}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1976}

\begin{DoxyItemize}
\item People want to be informed about or even participate in what Elektra looks like in the future.
\item Decision authors have some scientific background and want decisions based on science, and not only on opinions.
\item If assumptions, including this ones written here, are broken, decisions will be redone.
\item 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 \mbox{\hyperlink{doc_GOALS_md}{goals}}.
\item All decision reviewers want to help the decision authors to write a good decision.
\item Decision authors are the main force behind a decision and possibly also of specific solutions. Nevertheless they don\textquotesingle{}t want to avoid other solutions, are open to arguments/facts/etc. and incorporate all input of decision PR fairly.
\item We will always be able to reach an consensus even if it requires that the core or plugins get multiple implementations. We don\textquotesingle{}t need a vote (besides the approved review) or a benevolent dictatorship.
\item 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.
\item 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\textquotesingle{}s mind beforehand. Instead the decision process is a supported learning process.
\item People focus on getting the best solutions and not to wish for the impossible.
\item 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.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1977}{}\doxysection{Considered Alternatives}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1977}

\begin{DoxyItemize}
\item Issues like \href{https://issues.libelektra.org/4521}{\texttt{ https\+://issues.\+libelektra.\+org/4521}}
\item Git\+Hub discussions
\item Votings
\item The maintainer decides
\item PEPs\+: \href{https://peps.python.org}{\texttt{ https\+://peps.\+python.\+org}}
\item RFCs\+: \href{https://www.ietf.org/standards/rfcs/}{\texttt{ https\+://www.\+ietf.\+org/standards/rfcs/}}
\item Change requests\+: \href{https://en.wikipedia.org/wiki/Change_request}{\texttt{ https\+://en.\+wikipedia.\+org/wiki/\+Change\+\_\+request}}
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1978}{}\doxysection{Decision}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1978}
Decisions need to\+:


\begin{DoxyItemize}
\item be implementable within the next major release
\item be according to \mbox{\hyperlink{doc_GOALS_md}{Elektra\textquotesingle{}s goals}}
\item first be decided upon using the decision process described here
\end{DoxyItemize}

We base our decision process and template on\+:


\begin{DoxyItemize}
\item \href{http://eprints.cs.univie.ac.at/2345/1/02_Using_Patterns_to_Capture.pdf}{\texttt{ \textquotesingle{}\textquotesingle{}using patterns to capture architectural decisions\textquotesingle{}\textquotesingle{}}},
\item \href{http://docs.arc42.org/section-9/}{\texttt{ arc42 decisions}},
\item \href{https://adr.github.io/}{\texttt{ ADR}}, and
\item \href{https://github.com/rust-lang/rfcs}{\texttt{ RFCs in rust-\/lang}}.
\end{DoxyItemize}

We use the template \mbox{\hyperlink{doc_decisions_TEMPLATE_md}{TEMPLATE.md}}. Explanations of the template are in \mbox{\hyperlink{doc_decisions_EXPLANATIONS_md}{EXPLANATIONS.md}}.

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.\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1979}{}\doxysubsection{Drafts}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1979}
The first step is to create a PR with\+:


\begin{DoxyItemize}
\item {\bfseries{one}} decision, where at least the \char`\"{}\+Problem\char`\"{} is filled out and \char`\"{}\+Decision\char`\"{}, \char`\"{}\+Rationale\char`\"{} and \char`\"{}\+Implications\char`\"{} are {\bfseries{not}} yet filled out.
\item a link from \mbox{\hyperlink{doc_decisions_README_md}{README.md}} from the \char`\"{}\+Drafts\char`\"{} section to this decision.
\item optional backlinks from related decisions.
\end{DoxyItemize}

\begin{quote}
At least the problem must be clear to everyone involved before the decision can leave the \char`\"{}\+Drafts\char`\"{} status. It must be so clear that everyone would be able to write a test case that shows if a solution fixes the problem. \end{quote}
\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1980}{}\doxysubsection{In Discussion}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1980}
\begin{quote}
This step is mandatory. \end{quote}
Here you must ensure\+:


\begin{DoxyItemize}
\item problem, constraint and assumptions are well-\/explained and sound
\item consistency with other decisions
\item links from/to related decisions are created
\item there are several considered alternatives, each with rationale and implication
\item \char`\"{}\+Decision\char`\"{}, \char`\"{}\+Rationale\char`\"{} and \char`\"{}\+Implications\char`\"{} are {\bfseries{not}} yet filled out if there are people arguing for different options
\end{DoxyItemize}

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.\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1981}{}\doxysubsection{In Progress}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1981}

\begin{DoxyItemize}
\item You must include all further alternative proposals made in the \char`\"{}\+Considered Alternatives\char`\"{} section.
\item Now it is allowed to have the decision from the previous round in the \char`\"{}\+Decision\char`\"{} section.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1982}{}\doxysubsection{Decided}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1982}
\begin{quote}
This step is recommended. \end{quote}

\begin{DoxyItemize}
\item \char`\"{}\+Decision\char`\"{}, \char`\"{}\+Rationale\char`\"{} and \char`\"{}\+Implications\char`\"{} are now filled out and fixed according to the reviews
\item decisions of this status usually already have an implementation PR
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1983}{}\doxysubsection{Partially Implemented}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1983}
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 \char`\"{}\+Implication\char`\"{} must clearly say how much of the decision is already implemented.\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1984}{}\doxysubsection{Implemented}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1984}
\begin{quote}
This step is mandatory. \end{quote}

\begin{DoxyItemize}
\item Here the details of the decisions are stripped from the decision and moved to the documentation.
\item The documentation links to the decision.
\item The decision links to the new documentation.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1985}{}\doxysubsection{Rejected}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1985}
Alternatively, decisions might be rejected (i.\+e. status quo wins). These decision PRs are also merged for documentation purposes.\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1986}{}\doxysection{Rationale}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1986}

\begin{DoxyItemize}
\item The process is lightweight and simple.
\item The template makes sure important points are not forgotten.
\item Every decision is by design in its own file with its own Git history.
\item PRs allow to better support the constraint that everything must be within Elektra\textquotesingle{}s repository (also rejected PRs).
\item \char`\"{}\+Decision\char`\"{}, \char`\"{}\+Rationale\char`\"{} and \char`\"{}\+Implications\char`\"{} are filled out later to keep the discussion unbiased
\item PRs allow to suggest changes and review individual sentences of the decision.
\item Several \char`\"{}\+Related Decisions\char`\"{} 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.
\item The decision process is focused around the decision text (and not forum-\/like discussions), so that\+:
\begin{DoxyItemize}
\item The resulting text is understandable without reading any discussions.
\item There is a common understanding after only reading the decision text.
\item To avoid any gaps of reading discussions and the decision.
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1987}{}\doxysection{Implications}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1987}

\begin{DoxyItemize}
\item Proposal issues are obsolete.
\item The decision process creates at least\+:
\begin{DoxyItemize}
\item two chances to comment decisions, and
\item two commits in the Git history.
\end{DoxyItemize}
\item 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.
\end{DoxyItemize}\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1988}{}\doxysection{Related Decisions}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1988}
\hypertarget{doc_decisions_3_decided_decision_process_md_autotoc_md1989}{}\doxysection{Notes}\label{doc_decisions_3_decided_decision_process_md_autotoc_md1989}

\begin{DoxyItemize}
\item Discussions in issues/discussions are not prohibited. They don\textquotesingle{}t bring a decision forward, though. To not waste time, it is recommended to start with the decision process as described here asap.
\end{DoxyItemize}

Written by Markus Raab 10.\+10.\+2022. Second discussion round 28.\+10.\+2022. 