definition-of-done: lots of misc improvements
authorFelipe Balbi <balbi@ti.com>
Mon, 22 Apr 2013 15:18:58 +0000 (18:18 +0300)
committerFelipe Balbi <balbi@ti.com>
Thu, 25 Apr 2013 13:31:42 +0000 (16:31 +0300)
mostly related to indentation and styles, but
there are good stuff too:

. some more typo fixes
. added commas where necessary
. fixed/improved a list usage (lists in LaTeX
can be nested and LaTeX itself will
use different markers for each list)
. converted a period into a proper paragraph
which made the text slightly easier to
follow (to me, at least).

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

index 429c5a2abfb87907f3bf0602ec6cb09ba61a571d..7f3599c55fca6b1cbbefd0cd974d51c990fb1b83 100644 (file)
@@ -88,12 +88,13 @@ 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 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 it has been Submitted.  For more
-          details see section \ref{sec:lcpd-definition-submitted}.
+           details see section \ref{sec:lcpd-definition-documented}.
+    \item A Backlog item is not Done until it has been Submitted for
+           integration upstream.  For more details see section
+           \ref{sec:lcpd-definition-submitted}.
 \end{enumerate}
 
 \paragraph{}
@@ -132,14 +133,14 @@ In the LCPD definition of Done an item is not considered Done until it has been
 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 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.
+           Kernel Documentation) has been updated.
 \end{enumerate}
 
 The purpose of the documentation requirement is to make sure that users can
@@ -153,13 +154,15 @@ common area possible so that the documentation can be used by others.
 \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
+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{}
+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
@@ -167,15 +170,15 @@ 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.
+           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.
+           possible to allow time for feedback.
+    \item When/if feedback is given 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.
+           upstream immediately a backlog item must be created to track the
+           submission requirement.
 \end{enumerate}
 
 \paragraph{}
@@ -198,10 +201,10 @@ 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.
+more parts of the definition of Done do not apply, this should be agreed 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}
@@ -221,27 +224,28 @@ 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
+running on its 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.
+       \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{}
@@ -254,50 +258,53 @@ always be open backlog items showing the outstanding work remaining.
 \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}
+tasks above all other tasks.  The product owner must understand the following:
+
+\begin{itemize}
+       \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{itemize}
+                       \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{itemize}
+       \item Any delay in submitting work to the upstream adds to the
+               technical debt of the team in the following ways:
+               \begin{itemize}
+                       \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 if 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{itemize}
+       \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{itemize}
+                       \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{itemize}
+\end{itemize}
 
 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
+this commitment.  While emergencies can happen that may delay an upstream
+activity, it must always be with the knowledge in mind of the additional
 technical debt incurred by the team.