definition-of-done: Add initial definition
authorChase Maupin <chase.maupin@ti.com>
Thu, 18 Apr 2013 16:11:55 +0000 (11:11 -0500)
committerFelipe Balbi <balbi@ti.com>
Mon, 22 Apr 2013 14:51:03 +0000 (17:51 +0300)
* Add the initial definition of done.  Covers the three main
  components of the definition, how this differs from acceptance
  criteria, and most importantly how this comes together to
  support the upstream requirement.

* Also made sure to add a section detailing the commitment
  required from the product owner for this to work.

Signed-off-by: Chase Maupin <Chase.Maupin@ti.com>
Signed-off-by: Felipe Balbi <balbi@ti.com>
definition-of-done.tex

index 27d5154350f06d77d40b2aa18ba8a96929bccfef..4f693193b27ab69636b954912602efbe8fb77307 100644 (file)
@@ -8,3 +8,296 @@
 
 \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.