[ti-agile-manual/ti-agile-manual.git] / definition-of-done.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %%                                                                       %%
3 %% Copyright (C) 2013 Texas Instruments Incorporated - http://www.ti.com %%
4 %%                                                                       %%
5 %% Author: Felipe Balbi <balbi@ti.com>                                   %%
6 %%                                                                       %%
7 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 \chapter{Definition of Done}
10 \label{chap:definition-of-done}
12 \paragraph{}
13 In \textit{Scrum} the defininition of "Done" is a very important concept.  As
14 was discussed in chapter \ref{chap:the-sprint} the goal of Scrum is to
15 deliver a \textbf{working} increment at the end of each sprint.  This
16 means that the backlog items commited in a given sprint need to be "Done"
17 for that item to be working.
19 \paragraph{}
20 In section \ref{sec:why-common-def} we will discuss why we need a common
21 definition of Done and how this differs from the acceptance criteria.  In
22 section \ref{sec:lcpd-definition} we will cover the LCPD definition of done
23 with subsections to detail each piece.  Finally in section \ref{sec:upstreaming}
24 we will discuss how Upstreaming of development work fits into the definition
25 of Done.
27 \section{Why a Common Definition is Important}
28 \label{sec:why-common-def}
30 \paragraph{}
31 A great example of why there should be a definition of Done agreed to by all
32 parties is found in the movie \textit{"The Great Outdoors"}.  In this movie
33 the main character enters a local eating challenge to eat a 96-ounce steak
34 in order to win a free dinner for the family.  As the scene progresses you
35 watch him go from confident and enjoying himself to miserable and nauseous.
36 It becomes apparent that he has taken on a difficult task and at the very
37 end when he puts the last bite of steak in his mouth you can see that he
38 is relieved to be finished.  At this point he declares himself Done.  That is
39 where the real trouble starts because the owner of the steakhouse points to
40 the fat and gristle left over and says he hasn't eaten everything and is not
41 Done.  Clearly these two people had a different definition of Done and are now
42 in an awkward position.  The steak has already been eaten and can't be un-eaten.
43 The work that was put into both preparing and eating the steak is wasted and
44 someone is going to have to pay the bill.
46 \paragraph{}
47 It would have been better in the preceeding example if both had agreed to
48 what Done meant.  Similarly we need to have an agreement within LCPD of
49 what we mean when we say something is done prior to starting our work.  This
50 will help us to avoid situations where we have conflicting expectations and
51 avoid wasting work.  It also helps us in planning to make sure that we are
52 allocating enough time to accomplish an item because we agree on what is
53 required to mark the item as Done.
55 \subsection{How this Differs from Acceptance Criteria}
56 \label{sec:diff-acceptance-criteria}
58 \paragraph{}
59 Often when reading about Scrum you will see discussion of \textit{Acceptance
60 Criteria}.  This differs from the definition of Done in that Acceptance
61 Criteria are created per backlog item whereas the shared definition of Done
62 spans all backlog items.  The Acceptance Criteria for a backlog item may be
63 something like:
65 \begin{enumerate}
66     \item The driver support operating in mode x
67     \item The throughput for mode x should be no less than y
68     \item A functional test case has been created and delivered to the system
69           test team.
70     \item The Driver's User's Guide has been updated with the new feature.
71 \end{enumerate}
73 \paragraph{}
74 The above list differs from the shared definition of Done because it is
75 specific to that backlog item what is expected to be delivered for that
76 item for the Product Owner to accept the item as finished.
78 \paragraph{}
79 In section \ref{sec:lcpd-definition} we will see the LCPD definition of Done
80 and you will get a further sense of how this differs from Acceptance Criteria.
82 \section{LCPD Definition of Done}
83 \label{sec:lcpd-definition}
85 \paragraph{}
86 The purpose of this section is to outline the LCPD shared definition of Done
87 and give details pertaining to each part of that definition.  The LCPD
88 definition of Done can be broken down into the following main parts
90 \begin{enumerate}
91     \item A Backlog item is not Done until it has been tested.  For more
92             details see section \ref{sec:lcpd-definition-tested}.
93     \item A Backlog item is not Done until it has been documented.  For more
94             details see section \ref{sec:lcpd-definition-documented}.
95     \item A Backlog item is not Done until it has been Submitted for
96             integration upstream.  For more details see section
97             \ref{sec:lcpd-definition-submitted}.
98 \end{enumerate}
100 \paragraph{}
101 The above components define the understanding among the members of the LCPD
102 group of what it means to say an item is Done and forms the foundation for our
103 communication of status between ourselves and other groups.
105 \subsection{Tested}
106 \label{sec:lcpd-definition-tested}
108 \paragraph{}
109 In the LCPD definition of Done an item is not considered Done until it has
110 been \textbf{Tested}.  Since testing can have a variety of meanings to different
111 people this section will detail what we mean when we say tested.
113 \begin{enumerate}
114     \item There is a simple piece of code or scripting that will enable
115           automated validation of the new functionality.
116     \item Any environment setup required to run the test code is documented
117           within the code itself.
118     \item The test code has been provided to the system test team so it can
119           be added to the automation framework.
120 \end{enumerate}
122 \paragraph{}
123 The goal of the tested requirement is to make sure that the delivered feature
124 works as expected and that the results can be reproduced by others seeking
125 to verify the functionality in their configuration.
127 \subsection{Documented}
128 \label{sec:lcpd-definition-documented}
130 \paragraph{}
131 In the LCPD definition of Done an item is not considered Done until it has been
132 \textbf{Documented}.  Since documentation can take many forms the below list
133 will help to guide what is meant by documentation.
135 \begin{enumerate}
136     \item The driver's user's guide, if any, has been updated to list the new
137             feature or functionality.
138     \item The driver's user's guide, if any, has been updated to detail the
139             performance measurements if applicable.
140     \item The driver's user's guide, if any, has been updated with usage
141             information for the new feature or functionality.
142     \item Where appropriate the documentation in the source repository (i.e.
143             Kernel Documentation) has been updated.
144 \end{enumerate}
146 The purpose of the documentation requirement is to make sure that users can
147 easily and quickly identify what features are available, how to use them,
148 and the expected results.  The goal should be to document this in the most
149 common area possible so that the documentation can be used by others.
151 \subsection{Submitted}
152 \label{sec:lcpd-definition-submitted}
154 \paragraph{}
155 One of the most important pieces of the LCPD definition of Done is the
156 \textbf{Submitted} requirement.  In order to ensure that we are developing
157 software in a scalable and sustainable fashion, we must make sure that the
158 members of LCPD are pushing the development work they are doing upstream.
160 \paragraph{}
161 Without this commitment and requirement in the foundation of our work, it is
162 easy to reach a state where the majority of the development is done out of
163 tree.  This leads quickly to a technical debt that will exceed the team
164 capacity which, in turn, leads to either reduced feature development or
165 dropping support for previously developed code.
167 \paragraph{}
168 In order to avoid the accumulation of this technical debt the following
169 requirements have been put in place.
171 \begin{enumerate}
172     \item For each development item there must be a submission to the upstream
173             project.  This is to enable additional code review and start the
174             upstream acceptance process.
175     \item The upstream submission should be done as early in the sprint as
176             possible to allow time for feedback.
177     \item When/if feedback is given on the upstream submission a new backlog
178             item should be created to address this feedback.
179     \item In the rare case that a development effort cannot be submitted
180             upstream immediately a backlog item must be created to track the
181             submission requirement.
182 \end{enumerate}
184 \paragraph{}
185 The above requirements ensure that the work being done by the LCPD team is
186 constantly being pushed upstream.  More information will be given on this,
187 including the role of the Product Owner in section \ref{sec:upstreaming}.
190 \section{Exceptions}
191 \label{sec:exceptions}
193 \paragraph{}
194 In the above definition of Done there may be tasks where one or more of the
195 items do not apply or do not make sense.  For example time spent by a
196 developer acting in the role of an upstream maintainer may not use the above
197 definition.  Another example might be time a developer spends learning about
198 a new part or technology.  In this case the tested and submitted parts of the
199 definition may not apply, but perhaps the documented section can apply by
200 having the developer present a brownbag to the rest of the team about the
201 new technology area.
203 \paragraph{}
204 Sometimes a developer may implement a feature in the Integration kernel one
205 way but need to change it due to architecture changes or other reasons for
206 upstream.  In this case the upstream item may not be appropriate for the
207 Integration requirement.
209 \paragraph{}
210 The key point here is that at any time where there is a feeling that one or
211 more parts of the definition of Done do not apply, this should be agreed by the
212 entire scrum team.  It should be discussed as part of the sprint planning and
213 documented in the backlog item notes to make clear what is not required and
214 why.
216 \section{Upstreaming}
217 \label{sec:upstreaming}
219 \paragraph{}
220 As introduced in section \ref{sec:lcpd-definition-submitted} the primary way
221 to keep development from adding to the technical debt of the LCPD team is to
222 make sure that the work being done is submitted upstream.  However, just
223 submitting patches to the mailing list is not sufficient.  There must be an
224 accurate reflection of the time required to address feedback on patches and
225 work with the community to gain acceptance.  The purpose of this section is
226 to discuss how this fits into the LCPD flow and definition of done.
228 \paragraph{}
229 Realistically it is unlikely that any particular development item will be
230 developed and accepted into the upstream mainline within the timebox of a
231 given sprint.  It is also not completely possible to predict the exact number
232 of iterations acceptance of a feature might take.  This leaves us with the
233 problem of how to track this upstream requirement working with a community
234 running on its own schedule while at the same time being able to develop
235 items and reach an agreement of Done within a sprint.  The following steps
236 seek to balance these two requirements.
238 \begin{description}
239         \item[Step 1:] As discussed in section
240                 \ref{sec:lcpd-definition-submitted} for each development item
241                 there is a requirement that it be submitted to the upstream
242                 list.
243         \item[Step 2:] For each backlog item there should be a corresponding
244                 \textbf{"Merged"} backlog item created that will track when the
245                 upstream maintainer has merged the code.
246         \item[Step 3:] If feedback is received on the upstream submission a new
247                 item is added to the backlog to address the feedback and create
248                 a new submission.  This item will be scheduled in the next
249                 sprint.  This process is repeated until there is no more
250                 feedback.
251         \item[Step 4:] Once the maintainer has merged the code, the merged
252                 backlog item created in step 2 will be scheduled in the next
253                 sprint.  This item should contain the task of updating the list
254                 of merged code to reflect that the functionality has been
255                 accepted upstream.
256 \end{description}
258 \paragraph{}
259 Using the above steps until the code is merged into the mainline there will
260 always be open backlog items showing the outstanding work remaining.
262 \subsection{Product Owner Commitment}
263 \label{sec:product-owner-commitment}
265 \paragraph{}
266 It is important to note that the upstreaming effort will \textbf{NOT} work
267 without the commitment from the product owner to prioritize the upstream
268 tasks above all other tasks.  The product owner must understand the following:
270 \begin{itemize}
271         \item Once work has begun with the open source community to submit
272                 patches, that work must be given priority to be seen through to
273                 completion.  Failure to address feedback from the community in
274                 a timely manner will:
275                 \begin{itemize}
276                         \item Reduce credibility of developers in the open
277                                 source community.
278                         \item Delay the review of future submissions of the
279                                 patches.  After all, if the developer can't be
280                                 bothered to respond to feedback on their
281                                 patches why should others take time to give
282                                 that feedback.
283                 \end{itemize}
284         \item Any delay in submitting work to the upstream adds to the
285                 technical debt of the team in the following ways:
286                 \begin{itemize}
287                         \item Before a new LTS kernel version can be released
288                                 by LCPD all work that was developed but not
289                                 upstreamed must be ported to the new source
290                                 base.  This technical debt has historically
291                                 been seen to consume most if not all of the
292                                 team bandwidth which leads to lack of kernel
293                                 migration or dropped feature support.
294                         \item If the architecture changes while waiting for the
295                                 work to be upstreamed then the effort spent to
296                                 develop that work is wasted and new effort must
297                                 be added to the technical debt of the team to
298                                 re-do the work based on the new architecture.
299                 \end{itemize}
300         \item As open source merge windows approach the priority of any
301                 outstanding upstreams must be increased.  The impact of missing
302                 a merge window can be huge due to:
303                 \begin{itemize}
304                         \item The requirement to then carry the patch set until
305                                 the next merge window.
306                         \item If the merge window missed happens to be for the
307                                 next LTS kernel then the patch set must be
308                                 carried in the integration tree for the next
309                                 year.
310                 \end{itemize}
311 \end{itemize}
313 For the above reasons it is clear why the Product Owner \textbf{MUST} be
314 committed to upstream development and ensuring that priorities always reflect
315 this commitment.  While emergencies can happen that may delay an upstream
316 activity, it must always be with the knowledge in mind of the additional
317 technical debt incurred by the team.