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 details
92 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 more
96 details see section \ref{sec:lcpd-definition-submitted}.
97 \end{enumerate}
99 \paragraph{}
100 The above components define the understanding among the members of the LCPD
101 group of what it means to say an item is Done and forms the foundation for our
102 communication of status between ourselves and other groups.
104 \subsection{Tested}
105 \label{sec:lcpd-definition-tested}
107 \paragraph{}
108 In the LCPD definition of Done an item is not considered Done until it has
109 been \textbf{Tested}. Since testing can have a variety of meanings to different
110 people this section will detail what we mean when we say tested.
112 \begin{enumerate}
113 \item There is a simple piece of code or scripting that will enable
114 validation of the new functionality.
115 \item Any environment setup required to run the test code is documented
116 within the code itself.
117 \item The test code has been provided to the system test team so it can
118 be added to the automation framework.
119 \end{enumerate}
121 \paragraph{}
122 The goal of the tested requirement is to make sure that the delivered feature
123 works as expected and that the results can be reproduced by others seeking
124 to verify the functionality in their configuration.
126 \subsection{Documented}
127 \label{sec:lcpd-definition-documented}
129 \paragraph{}
130 In the LCPD definition of Done an item is not considered Done until it has been
131 \textbf{Documented}. Since documentation can take many forms the below list
132 will help to guide what is meant by documentation.
134 \begin{enumerate}
135 \item The driver's user's guide if any has been updated to list the new
136 feature or functionality.
137 \item The driver's user's guide if any has been updated to detail the
138 performance measurements if applicable.
139 \item The driver's user's guide if any has been updated with usage
140 information for the new feature or functionality.
141 \item Where appropriate the documentation in the source repository (i.e.
142 Kernel Documentation) has been updated.
143 \end{enumerate}
145 The purpose of the documentation requirement is to make sure that users can
146 easily and quickly identify what features are available, how to use them,
147 and the expected results. The goal should be to document this in the most
148 common area possible so that the documentation can be used by others.
150 \subsection{Submitted}
151 \label{sec:lcpd-definition-submitted}
153 \paragraph{}
154 One of the most important pieces of the LCPD definition of Done is the
155 \textbf{Submitted} requirement. In order to ensure that we are developing
156 software in a scalable and sustainable fashion we must make sure that the
157 members of LCPD are pushing the development work they are doing upstream.
158 Without this commitment and requirement in the foundation of our work it
159 is easy to reach a state where the majority of the development is done
160 out of tree. This leads quickly to a technical debt that will exceed the
161 team capacity which in turn leads to either reduced feature development
162 or dropping support for previously developed code.
164 \paragraph{}
165 In order to avoid the accumulation of this technical debt the following
166 requirements have been put in place.
168 \begin{enumerate}
169 \item For each development item there must be a submission to the upstream
170 project. This is to enable additional code review and start the
171 upstream acceptance process.
172 \item The upstream submission should be done as early in the sprint as
173 possible to allow time for feedback.
174 \item When/if feedback is give on the upstream submission a new backlog
175 item should be created to address this feedback.
176 \item In the rare case that a development effort cannot be submitted
177 upstream immediately a backlog item must be created to track
178 the submission requirement.
179 \end{enumerate}
181 \paragraph{}
182 The above requirements ensure that the work being done by the LCPD team is
183 constantly being pushed upstream. More information will be given on this,
184 including the role of the Product Owner in section \ref{sec:upstreaming}.
186 \section{Exceptions}
187 \label{sec:exceptions}
189 \paragraph{}
190 In the above definition of Done there may be tasks where one or more of the
191 items do not apply or do not make sense. For example time spent by a
192 developer acting in the role of an upstream maintainer may not use the above
193 definition. Another example might be time a developer spends learning about
194 a new part or technology. In this case the tested and submitted parts of the
195 definition may not apply, but perhaps the documented section can apply by
196 having the developer present a brownbag to the rest of the team about the
197 new technology area.
199 \paragraph{}
200 The key point here is that at any time where there is a feeling that one or
201 more parts of the definition of Done does not apply this should be agreed
202 to by the entire scrum team. It should be discussed as part of the sprint
203 planning and documented in the backlog item notes to make clear what is not
204 required and why.
206 \section{Upstreaming}
207 \label{sec:upstreaming}
209 \paragraph{}
210 As introduced in section \ref{sec:lcpd-definition-submitted} the primary way
211 to keep development from adding to the technical debt of the LCPD team is to
212 make sure that the work being done is submitted upstream. However, just
213 submitting patches to the mailing list is not sufficient. There must be an
214 accurate reflection of the time required to address feedback on patches and
215 work with the community to gain acceptance. The purpose of this section is
216 to discuss how this fits into the LCPD flow and definition of done.
218 \paragraph{}
219 Realistically it is unlikely that any particular development item will be
220 developed and accepted into the upstream mainline within the timebox of a
221 given sprint. It is also not completely possible to predict the exact number
222 of iterations acceptance of a feature might take. This leaves us with the
223 problem of how to track this upstream requirement working with a community
224 running on it's own schedule while at the same time being able to develop
225 items and reach an agreement of Done within a sprint. The following steps
226 seek to balance these two requirements.
228 \begin{description}
229 \item[Step 1:] As discussed in section \ref{sec:lcpd-definition-submitted}
230 for each development item there is a requirement that it
231 be submitted to the upstream list.
232 \item[Step 2:] For each backlog item there should be a corresponding
233 \textbf{"Merged"} backlog item created that will track
234 when the upstream maintainer has merged the code.
235 \item[Step 3:] If feedback is received on the upstream submission a new
236 item is added to the backlog to address the feedback and
237 create a new submission. This item will be scheduled in
238 the next sprint. This process is repeated until there is
239 no more feedback.
240 \item[Step 4:] Once the maintainer has merged the code the merged backlog
241 item created in step 2 will be scheduled in the next sprint.
242 This item should contain the task of updating the list of
243 merged code to reflect that the functionality has been
244 accepted upstream.
245 \end{description}
247 \paragraph{}
248 Using the above steps until the code is merged into the mainline there will
249 always be open backlog items showing the outstanding work remaining.
251 \subsection{Product Owner Commitment}
252 \label{sec:product-owner-commitment}
254 \paragraph{}
255 It is important to note that the upstreaming effort will \textbf{NOT} work
256 without the commitment from the product owner to prioritize the upstream
257 tasks above all other tasks. The product owner must understand the following.
259 \begin{enumerate}
260 \item[*] Once work has begun with the open source community to submit
261 patches that work must be given priority to be seen through to
262 completion. Failure to address feedback from the community in
263 a timely manner will:
264 \begin{enumerate}
265 \item[-] Reduce credibility of developers in the open source
266 community.
267 \item[-] Delay the review of future submissions of the patches.
268 After all, if the developer can't be bothered to
269 respond to feedback on their patches why should others
270 take time to give that feedback.
271 \end{enumerate}
272 \item[*] Any delay in submitting work to the upstream adds to the
273 technical debt of the team in the following ways:
274 \begin{enumerate}
275 \item[-] Before a new LTS kernel version can be released by LCPD
276 all work that was developed but not upstreamed must be
277 ported to the new source base. This technical debt has
278 historically been seen to consume most of not all of the
279 team bandwidth which leads to lack of kernel migration or
280 dropped feature support.
281 \item[-] If the architecture changes while waiting for the work to
282 be upstreamed then the effort spent to develop that work
283 is wasted and new effort must be added to the technical
284 debt of the team to re-do the work based on the new
285 architecture.
286 \end{enumerate}
287 \item[*] As open source merge windows approach the priority of any
288 outstanding upstreams must be increased. The impact of missing
289 a merge window can be huge due to:
290 \begin{enumerate}
291 \item[-] The requirement to then carry the patch set until the
292 next merge window.
293 \item[-] If the merge window missed happens to be for the next
294 LTS kernel then the patch set must be carried in the
295 integration tree for the next year.
296 \end{enumerate}
297 \end{enumerate}
299 For the above reasons it is clear why the Product Owner \textbf{MUST} be
300 committed to upstream development and ensuring that priorities always reflect
301 this commitment. While emergencies can happen than may delay an upstream
302 activity it must always be with the knowledge in mind of the additional
303 technical debt incurred by the team.