\label{doc_decisions_5_partially_implemented_decision_process_md_md_doc_decisions_5_partially_implemented_decision_process}%
\Hypertarget{doc_decisions_5_partially_implemented_decision_process_md_md_doc_decisions_5_partially_implemented_decision_process}%
 \hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2189}{}\doxysection{Problem}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2189}
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.


\begin{DoxyItemize}
\item Discussing fundamental problems in forum-\/like threads showed to be repetitive and ineffective.
\item Decisions by supervisors are undemocratic.
\item Decisions in meetings are nontransparent for the outside world.
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2190}{}\doxysubsection{Terminology}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2190}

\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 substantial changes for a decision.
\item {\ttfamily Decision author}\+: Is the person who creates the decision PR.
\item {\ttfamily Decision reviewers}\+: Are the people who review the decision PR.
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2191}{}\doxysubsection{Main Purpose}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2191}
The main purpose of decisions is


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

\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 to decisions.
\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 in a 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 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 not read the discussions surrounding the decision. It is encouraged that at least one decision reviewers provides a review {\itshape without} participating in the discussion. This ensures that there aren\textquotesingle{}t any unintentional shared assumptions between discussion participants.
\item Reviews focus on the \char`\"{}\+Problem\char`\"{} section first, and only when that is agreed upon focus in the other parts.
\item The decision author invites several decision reviewers. Ask for help in the decision PR if you do not know whom to invite.
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2193}{}\doxysection{Assumptions}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2193}

\begin{DoxyItemize}
\item People want to be informed about or even participate in what Elektra looks like in the future.
\item People actually use Elektra and propose only what they need for their use cases.
\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 For important decisions, we will able to reach an consensus even if it requires that the core or plugins get multiple implementations. We accept indefinite postponement of lesser important decisions, where there is strong disagreement about the problem or the best solution. Thus we don\textquotesingle{}t need a vote (besides the approved review) or a benevolent dictatorship.
\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.
\item The decision process itself isn\textquotesingle{}t a barrier for people to write their first decision.
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2194}{}\doxysection{Solutions}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2194}

\begin{DoxyItemize}
\item Create a decision process tailored to Elektra
\item Issues like \href{https://issues.libelektra.org/4521}{\texttt{ https\+://issues.\+libelektra.\+org/4521}} (often did not result to a PR that documented the outcome)
\item Git\+Hub discussions (-\/$\vert$$\vert$-\/)
\item Votings (low participation and people often didn\textquotesingle{}t inform themselves what the choices are)
\item maintainer decides (was the situation before)
\item PEPs\+: \href{https://peps.python.org}{\texttt{ https\+://peps.\+python.\+org}} (tailored for programming language specifications, not ideal for architectural decisions)
\item Rust RFCs\+: \href{https://www.ietf.org/standards/rfcs/}{\texttt{ https\+://www.\+ietf.\+org/standards/rfcs/}} (-\/$\vert$$\vert$-\/, see also \href{https://forge.rust-lang.org/compiler/mcp.html}{\texttt{ https\+://forge.\+rust-\/lang.\+org/compiler/mcp.\+html}})
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2195}{}\doxysection{Decision}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2195}
We use a decision process tailored to Elektra, in which 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 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}}.

Steps are described in \mbox{\hyperlink{doc_decisions_STEPS_md}{STEPS.md}}\+:


\begin{DoxyItemize}
\item Decision authors are the main force to improve the text to get a decision forward.
\item Decision authors and decision reviewers together decide about which step a decision currently has.
\item Each mandatory step requires two reviews and the merging of the decision PR.
\item 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 and improves.
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2196}{}\doxysection{Rationale}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2196}

\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 decisions).
\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 As \char`\"{}\+Decided\char`\"{}/\char`\"{}\+Implemented\char`\"{} decisions need a special decision PR, we cannot merge a \char`\"{}\+Decided\char`\"{}/\char`\"{}\+Implemented\char`\"{} decision PR by accident.
\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_5_partially_implemented_decision_process_md_autotoc_md2197}{}\doxysection{Implications}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2197}

\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 Decision PRs might be merged quite often until they reach the step \char`\"{}\+Implemented\char`\"{}. They might even be merged several times within the same step.
\item Decisions encourage to write documentation before actually writing code.
\item The proposal encourages healthier discussions despite cognitive biases we all have, see in Notes below.
\end{DoxyItemize}

Partially implemented because of open tasks\+:


\begin{DoxyItemize}
\item rename Considered Alternatives to Solutions
\item rename Steps
\end{DoxyItemize}\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2198}{}\doxysection{Related Decisions}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2198}
This is the only non-\/technical decision, so no issues are related.\hypertarget{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2199}{}\doxysection{Notes}\label{doc_decisions_5_partially_implemented_decision_process_md_autotoc_md2199}

\begin{DoxyItemize}
\item The first idea often is not the best, don\textquotesingle{}t fixate on it. Abraham Luchins called this the “\+Einstellung effect.\+” Thus we encourage to generate as many ideas as possible for any problem (interrupt effect).
\item We have a tendency to add\+: Take courage to also propose solutions that (mostly) remove code. See Leidy Klotz et al., e.\+g. “\+People systematically overlook subtractive changes“.
\item Failures are not a bad thing. It is a good thing to have \char`\"{}rejected\char`\"{} decisions for future references and to recheck if assumptions change.
\item Decisions are about \char`\"{}\+Why?\char`\"{} and not about \char`\"{}\+Who?\char`\"{} or \char`\"{}\+When?\char`\"{}. Such discussions should be in separate issues.
\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.
\item Make sure that moving between the stages is detected by git. E.\+g. rename in a commit that doesn\textquotesingle{}t rewrite too much of the decision.
\item See also change requests\+: \href{https://en.wikipedia.org/wiki/Change_request}{\texttt{ https\+://en.\+wikipedia.\+org/wiki/\+Change\+\_\+request}}
\end{DoxyItemize}

Written by Markus Raab.


\begin{DoxyItemize}
\item First discussion round starting 10.\+10.\+2022.
\item Second discussion round starting 28.\+10.\+2022.
\item Third discussion round starting 6.\+11.\+2022. 
\end{DoxyItemize}