diff --git a/definition-of-done.tex b/definition-of-done.tex
index 27d5154350f06d77d40b2aa18ba8a96929bccfef..4f693193b27ab69636b954912602efbe8fb77307 100644 (file)
--- a/definition-of-done.tex
+++ b/definition-of-done.tex
\chapter{Definition of Done}
\label{chap:definition-of-done}
+
+\paragraph{}
+In \textit{Scrum} the defininition of "Done" is a very important concept. As
+was discussed in chapter \ref{chap:the-sprint} the goal of Scrum is to
+deliver a \textbf{working} increment at the end of each sprint. This
+means that the backlog items commited in a given sprint need to be "Done"
+for that item to be working.
+
+\paragraph{}
+In section \ref{sec:why-common-def} we will discuss why we need a common
+definition of Done and how this differs from the acceptance criteria. In
+section \ref{sec:lcpd-definition} we will cover the LCPD definition of done
+with subsections to detail each piece. Finally in section \ref{sec:upstreaming}
+we will discuss how Upstreaming of development work fits into the definition
+of Done.
+
+\section{Why a Common Definition is Important}
+\label{sec:why-common-def}
+
+\paragraph{}
+A great example of why there should be a definition of Done agreed to by all
+parties is found in the movie \textit{"The Great Outdoors"}. In this movie
+the main character enters a local eating challenge to eat a 96-ounce steak
+in order to win a free dinner for the family. As the scene progresses you
+watch him go from confident and enjoying himself to miserable and nauseous.
+It becomes apparent that he has taken on a difficult task and at the very
+end when he puts the last bite of steak in his mouth you can see that he
+is relieved to be finished. At this point he declares himself Done. That is
+where the real trouble starts because the owner of the steakhouse points to
+the fat and gristle left over and says he hasn't eaten everything and is not
+Done. Clearly these two people had a different definition of Done and are now
+in an awkward position. The steak has already been eaten and can't be un-eaten.
+The work that was put into both preparing and eating the steak is wasted and
+someone is going to have to pay the bill.
+
+\paragraph{}
+It would have been better in the preceeding example if both had agreed to
+what Done meant. Similarly we need to have an agreement within LCPD of
+what we mean when we say something is done prior to starting our work. This
+will help us to avoid situations where we have conflicting expectations and
+avoid wasting work. It also helps us in planning to make sure that we are
+allocating enough time to accomplish an item because we agree on what is
+required to mark the item as Done.
+
+\subsection{How this Differs from Acceptance Criteria}
+\label{sec:diff-acceptance-criteria}
+
+\paragraph{}
+Often when reading about Scrum you will see discussion of \textit{Acceptance
+Criteria}. This differs from the definition of Done in that Acceptance
+Criteria are created per backlog item whereas the shared definition of Done
+spans all backlog items. The Acceptance Criteria for a backlog item may be
+something like:
+
+\begin{enumerate}
+ \item The driver support operating in mode x
+ \item The throughput for mode x should be no less than y
+ \item A functional test case has been created and delivered to the system
+ test team.
+ \item The Driver's User's Guide has been updated with the new feature.
+\end{enumerate}
+
+\paragraph{}
+The above list differs from the shared definition of Done because it i
+specific to that backlog item what what is expected to be delivered for that
+item for the Product Owner to accept the item as finished.
+
+\paragraph{}
+In section \ref{sec:lcpd-definition} we will see the LCPD definition of Done
+and you will get a further sense of how this differs from Acceptance Criteria.
+
+\section{LCPD Definition of Done}
+\label{sec:lcpd-definition}
+
+\paragraph{}
+The purpose of this section is to outline the LCPD shared definition of Done
+and give details pertaining to each part of that definition. The LCPD
+definition of Done can be broken down into the following main parts
+
+\begin{enumerate}
+ \item A Backlog item is not Done until it has been tested. For more details
+ see section \ref{sec:lcpd-definition-tested}.
+ \item A Backlog item is not Done until it has been documented. For more
+ details see section \ref{sec:lcpd-definition-documented}.
+ \item A Backlog item is not Done until is has been Submitted. For more
+ details see section \ref{sec:lcpd-definition-submitted}.
+\end{enumerate}
+
+\paragraph{}
+The above components define the understanding among the memberes of the LCPD
+group of what it means to say an item Done and forms the foundation for our
+communication of status between ourselves and other groups.
+
+\subsection{Tested}
+\label{sec:lcpd-definition-tested}
+
+\paragraph{}
+In the LCPD definition of Done an item is not considered Done until it has
+been \textbf{Tested}. Since testing can have a variety of meanings to different
+people this section will detail what we mean when we say tested.
+
+\begin{enumerate}
+ \item There is a simple piece of code or scripting that will enable
+ validation of the new functionality.
+ \item Any environment setup required to run the test code is documented
+ within the code itself.
+ \item The test code has been provided to the system test team so it can
+ be added to the automation framework.
+\end{enumerate}
+
+\paragraph{}
+The goal of the tested requirement is to make sure that the delivered feature
+works as expected and that the results can be reproduced by others seeking
+to verify the functionality in their configuration.
+
+\subsection{Documented}
+\label{sec:lcpd-definition-documented}
+
+\paragraph{}
+In the LCPD definition of Done an item is not considered Done until it has been
+\textbf{Documented}. Since documentation can take many forms the below list
+will help to guide what is meant by documentation.
+
+\begin{enumerate}
+ \item The driver's user's guide if any has been updated to list the new
+ feature or functionality.
+ \item The driver's user's guide if any has been updated to detail the
+ performance measurements if applicable.
+ \item The driver's user's guide if any has been updated with usage
+ information for the new feature or functionality.
+ \item Where appropriate the documentation in the source repository (i.e.
+ Kernel Documentation) has been updated.
+\end{enumerate}
+
+The purpose of the documentation requirement is to make sure that users can
+easily and quickly identify what features are available, how to use them,
+and the expected results. The goal should be to document this in the most
+common area possible so that the documentation can be used by others.
+
+\subsection{Submitted}
+\label{sec:lcpd-definition-submitted}
+
+\paragraph{}
+One of the most important pieces of the LCPD definition of Done is the
+\textbf{Submitted} requirement. In order to ensure that we are developing
+software in a scalable and sustainable fashion we must make sure that the
+members of LCPD are pushing the development work they are doing upstream.
+Without this commitment and requirement in the foundation of our work it
+is easy to reach a state where the majority of the development is done
+out of tree. This leads quickly to a technical debt that will exceed the
+team capacity which in turn leads to either reduced feature development
+or dropping support for previously developed code.
+
+\paragraph{}
+In order to avoid the accumulation of this technical debt the following
+requirements have been put in place.
+
+\begin{enumerate}
+ \item For each development item there must be a submission to the upstream
+ project. This is to enable additional code review and start the
+ upstream acceptance process.
+ \item The upstream submission should be done as early in the sprint as
+ possible to allow time for feedback.
+ \item When/if feedback is give on the upstream submission a new backlog
+ item should be created to address this feedback.
+ \item In the rare case that a development effort cannot be submitted
+ upstream immediately a backlog item must be created to track
+ the submission requirement.
+\end{enumerate}
+
+\paragraph{}
+The above requirements ensure that the work being done by the LCPD team is
+constantly being pushed upstream. More information will be given on this,
+including the role of the Product Owner in section \ref{sec:upstreaming}.
+
+\section{Exceptions}
+\label{sec:exceptions}
+
+\paragraph{}
+In the above definition of Done there may be tasks where one or more of the
+items do not apply or do not make sense. For example time spent by a
+developer acting in the role of an upstream maintainer may not use the above
+definition. Another example might be time a developer spends learning about
+a new part or technology. In this case the tested and submitted parts of the
+definition may not apply, but perhaps the documented section can apply by
+having the developer present a brownbag to the rest of the team about the
+new technology area.
+
+\paragraph{}
+The key point here is that at any time where there is a feeling that one or
+more parts of the definition of Done does not apply this should be agreed
+to by the entire scrum team. It should be discussed as part of the sprint
+planning and documented in the backlog item notes to make clear what is not
+required and why.
+
+\section{Upstreaming}
+\label{sec:upstreaming}
+
+\paragraph{}
+As introduced in section \ref{sec:lcpd-definition-submitted} the primary way
+to keep development from adding to the technical debt of the LCPD team is to
+make sure that the work being done is submitted upstream. However, just
+submitting patches to the mailing list is not sufficient. There must be an
+accurate reflection of the time required to address feedback on patches and
+work with the community to gain acceptance. The purpose of this section is
+to discuss how this fits into the LCPD flow and definition of done.
+
+\paragraph{}
+Realistically it is unlikely that any particular development item will be
+developed and accepted into the upstream mainline within the timebox of a
+given sprint. It is also not completely possible to predict the exact number
+of iterations acceptance of a feature might take. This leaves us with the
+problem of how to track this upstream requirement working with a community
+running on it's own schedule while at the same time being able to develop
+items and reach an agreement of Done within a sprint. The following steps
+seek to balance these two requirements.
+
+\begin{description}
+ \item[Step 1:] As discussed in section \ref{sec:lcpd-definition-submitted}
+ for each development item there is a requirement that it
+ be submitted to the upstream list.
+ \item[Step 2:] For each backlog item there should be a corresponding
+ \textbf{"Merged"} backlog item created that will track
+ when the upstream maintainer has merged the code.
+ \item[Step 3:] If feedback is received on the upstream submission a new
+ item is added to the backlog to address the feedback and
+ create a new submission. This item will be scheduled in
+ the next sprint. This process is repeated until there is
+ no more feedback.
+ \item[Step 4:] Once the maintainer has merged the code the merged backlog
+ item created in step 2 will be scheduled in the next sprint.
+ This item should contain the task of updating the list of
+ merged code to reflect that the functionality has been
+ accepted upstream.
+\end{description}
+
+\paragraph{}
+Using the above steps until the code is merged into the mainline there will
+always be open backlog items showing the outstanding work remaining.
+
+\subsection{Product Owner Commitment}
+\label{sec:product-owner-commitment}
+
+\paragraph{}
+It is important to note that the upstreaming effort will \textbf{NOT} work
+without the commitment from the product owner to prioritize the upstream
+tasks above all other tasks. The product owner must understand the following.
+
+\begin{enumerate}
+ \item[*] Once work has begun with the open source community to submit
+ patches that work must be given priority to be seen through to
+ completion. Failure to address feedback from the community in
+ a timely manner will:
+ \begin{enumerate}
+ \item[-] Reduce credibility of developers in the open source
+ community.
+ \item[-] Delay the review of future submissions of the patches.
+ After all, if the developer can't be bothered to
+ respond to feedback on their patches why should others
+ take time to give that feedback.
+ \end{enumerate}
+ \item[*] Any delay in submitting work to the upstream adds to the
+ technical debt of the team in the following ways:
+ \begin{enumerate}
+ \item[-] Before a new LTS kernel version can be released by LCPD
+ all work that was developed but not upstreamed must be
+ ported to the new source base. This technical debt has
+ historically been seen to consume most of not all of the
+ team bandwidth which leads to lack of kernel migration or
+ dropped feature support.
+ \item[-] If the architecture changes while waiting for the work to
+ be upstreamed then the effort spent to develop that work
+ is wasted and new effort must be added to the technical
+ debt of the team to re-do the work based on the new
+ architecture.
+ \end{enumerate}
+ \item[*] As open source merge windows approach the priority of any
+ outstanding upstreams must be increased. The impact of missing
+ a merge window can be huge due to:
+ \begin{enumerate}
+ \item[-] The requirement to then carry the patch set until the
+ next merge window.
+ \item[-] If the merge window missed happens to be for the next
+ LTS kernel then the patch set must be carried in the
+ integration tree for the next year.
+ \end{enumerate}
+\end{enumerate}
+
+For the above reasons it is clear why the Product Owner \textbf{MUST} be
+committed to upstream development and ensuring that priorities always reflect
+this commitment. While emergencies can happen than may delay an upstream
+activity it must always be with the knowledge in mind of the additional
+technical debt incurred by the team.