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