life-cycle-of-story: Add creation of upstream stories
[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 %% Author: Chase Maupin <chase.maupin@ti.com>                            %%
7 %%                                                                       %%
8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10 \chapter{Definition of Done}
11 \label{chap:definition-of-done}
13 \paragraph{}
14 In \textit{Scrum} the defininition of "Done" is a very important concept.  As
15 was discussed in chapter \ref{chap:the-sprint} the goal of Scrum is to
16 deliver a \textbf{working} increment at the end of each sprint.  This
17 means that the backlog items commited in a given sprint need to be "Done"
18 for that item to be working.
20 \paragraph{}
21 In section \ref{sec:why-common-def} we will discuss why we need a common
22 definition of Done and how this differs from the acceptance criteria.  In
23 section \ref{sec:lcpd-definition} we will cover the LCPD definition of done
24 with subsections to detail each piece.  Finally in section \ref{sec:upstreaming}
25 we will discuss how Upstreaming of development work fits into the definition
26 of Done.
28 \section{Why a Common Definition is Important}
29 \label{sec:why-common-def}
31 \paragraph{}
32 A great example of why there should be a definition of Done agreed to by all
33 parties is found in the movie \textit{"The Great Outdoors"}.  In this movie
34 the main character enters a local eating challenge to eat a 96-ounce steak
35 in order to win a free dinner for the family.  As the scene progresses you
36 watch him go from confident and enjoying himself to miserable and nauseous.
37 It becomes apparent that he has taken on a difficult task and at the very
38 end when he puts the last bite of steak in his mouth you can see that he
39 is relieved to be finished.  At this point he declares himself Done.  That is
40 where the real trouble starts because the owner of the steakhouse points to
41 the fat and gristle left over and says he hasn't eaten everything and is not
42 Done.  Clearly these two people had a different definition of Done and are now
43 in an awkward position.  The steak has already been eaten and can't be un-eaten.
44 The work that was put into both preparing and eating the steak is wasted and
45 someone is going to have to pay the bill.
47 \paragraph{}
48 It would have been better in the preceeding example if both had agreed to
49 what Done meant.  Similarly we need to have an agreement within LCPD of
50 what we mean when we say something is done prior to starting our work.  This
51 will help us to avoid situations where we have conflicting expectations and
52 avoid wasting work.  It also helps us in planning to make sure that we are
53 allocating enough time to accomplish an item because we agree on what is
54 required to mark the item as Done.
56 \subsection{How this Differs from Acceptance Criteria}
57 \label{sec:diff-acceptance-criteria}
59 \paragraph{}
60 Often when reading about Scrum you will see discussion of \textit{Acceptance
61 Criteria}.  This differs from the definition of Done in that Acceptance
62 Criteria are created per backlog item whereas the shared definition of Done
63 spans all backlog items.  The Acceptance Criteria for a backlog item may be
64 something like:
66 \begin{enumerate}
67     \item The driver support operating in mode x
68     \item The throughput for mode x should be no less than y
69     \item A functional test case has been created and delivered to the system
70           test team.
71     \item The Driver's User's Guide has been updated with the new feature.
72 \end{enumerate}
74 \paragraph{}
75 The above list differs from the shared definition of Done because it is
76 specific to that backlog item what is expected to be delivered for that
77 item for the Product Owner to accept the item as finished.
79 \paragraph{}
80 In section \ref{sec:lcpd-definition} we will see the LCPD definition of Done
81 and you will get a further sense of how this differs from Acceptance Criteria.
83 \section{LCPD Definition of Done}
84 \label{sec:lcpd-definition}
86 \paragraph{}
87 The purpose of this section is to outline the LCPD shared definition of Done
88 and give details pertaining to each part of that definition.  The LCPD
89 definition of Done can be broken down into the following main parts
91 \begin{enumerate}
92     \item A Backlog item is not Done until it has been tested.  For more
93             details see section \ref{sec:lcpd-definition-tested}.
94     \item A Backlog item is not Done until it has been documented.  For more
95             details see section \ref{sec:lcpd-definition-documented}.
96     \item A Backlog item is not Done until it has been Submitted for
97             acceptance upstream.  For more details see section
98             \ref{sec:lcpd-definition-submitted}.
99 \end{enumerate}
101 \paragraph{}
102 The above components define the understanding among the members of the LCPD
103 group of what it means to say an item is Done and forms the foundation for our
104 communication of status between ourselves and other groups.
106 \subsection{Tested}
107 \label{sec:lcpd-definition-tested}
109 \paragraph{}
110 In the LCPD definition of Done an item is not considered Done until it has
111 been \textbf{Tested}.  Since testing can have a variety of meanings to different
112 people this section will detail what we mean when we say tested.
114 \begin{enumerate}
115     \item There is a simple piece of code or scripting that will enable
116           automated validation of the new functionality.
117     \item Any environment setup required to run the test code is documented
118           within the code itself.
119     \item The developer has added the code to the automation framework so
120           that it can be tested in all future kernels.  The developer can
121           work with the system test team if they need assistance in adding
122           their code 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 \paragraph{}
131 This is also critical so that we can provide test reports for customers
132 looking to migrate from one kernel version to another.  By being able to
133 show that the same tests pass in the new kernel that passed in the old
134 kernel we can alleviate fears and ease the migration.
136 \subsection{Documented}
137 \label{sec:lcpd-definition-documented}
139 \paragraph{}
140 In the LCPD definition of Done an item is not considered Done until it has been
141 \textbf{Documented}.  Since documentation can take many forms the below list
142 will help to guide what is meant by documentation.
144 \begin{enumerate}
145     \item The driver's user's guide, if any, has been updated to list the new
146             feature or functionality.
147     \item The driver's user's guide, if any, has been updated to detail the
148             performance measurements if applicable.
149     \item The driver's user's guide, if any, has been updated with usage
150             information for the new feature or functionality.
151     \item Where appropriate the documentation in the source repository (i.e.
152             Kernel Documentation) has been updated.
153 \end{enumerate}
155 The purpose of the documentation requirement is to make sure that users can
156 easily and quickly identify what features are available, how to use them,
157 and the expected results.  The goal should be to document this in the most
158 common area possible so that the documentation can be used by others.
160 \subsection{Submitted}
161 \label{sec:lcpd-definition-submitted}
163 \paragraph{}
164 One of the most important pieces of the LCPD definition of Done is the
165 \textbf{Submitted} requirement.  In order to ensure that we are developing
166 software in a scalable and sustainable fashion, we must make sure that the
167 members of LCPD are pushing the development work they are doing upstream.
169 \paragraph{}
170 Without this commitment and requirement in the foundation of our work, it is
171 easy to reach a state where the majority of the development is done out of
172 tree.  This leads quickly to a technical debt that will exceed the team
173 capacity which, in turn, leads to either reduced feature development or
174 dropping support for previously developed code.
176 \paragraph{}
177 In order to avoid the accumulation of this technical debt the following
178 requirements have been put in place.
180 \begin{enumerate}
181     \item For each development item there must be a submission to the upstream
182             project.  This is to enable additional code review and start the
183             upstream acceptance process.
184     \item The upstream submission should be done as early in the sprint as
185             possible to allow time for feedback.
186     \item When/if feedback is given on the upstream submission a new backlog
187             item should be created to address this feedback.
188     \item In the rare case that a development effort cannot be submitted
189             upstream immediately a backlog item must be created to track the
190             submission requirement.
191     \item When a development patch set has been submitted upstream a story
192         should be created by the developer that tracks the merge of the patches
193         into Linus' linux.git tree.  This item will ensure that we continue
194         to track the progress of those patches as they go upstream.  Once the
195         patches have been merged this item can be scheduled for the system
196         test team to validate the upstream driver using the automated system.
197 \end{enumerate}
199 \paragraph{}
200 The above requirements ensure that the work being done by the LCPD team is
201 constantly being pushed upstream.  More information will be given on this,
202 including the role of the Product Owner in section \ref{sec:upstreaming}.
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 brown bag to the rest of the team about the
216 new technology area.
218 \paragraph{}
219 Sometimes a developer may have a feature implemented but they have a
220 dependency on the work of another developer being submitted first, or perhaps
221 the maintainer is not ready for them to send the patches to them yet.
223 \paragraph{}
224 The key point here is that at any time where there is a feeling that one or
225 more parts of the definition of Done do not apply, this should be agreed by the
226 entire scrum team.  It should be discussed as part of the sprint planning and
227 documented in the backlog item notes to make clear what is not required and
228 why.  Additionally there should always be a backlog item created to track the
229 submission for later to make sure it does not get forgotten.
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 upstream submission there should be a corresponding
259                 \textbf{"Merged"} backlog item created that will track when the
260                 code has been merged to Linus' master branch and can be tested in
261         the Linux mainline.
262         \item[Step 3:] If feedback is received on the upstream submission a new
263                 item is added to the backlog to address the feedback and create
264                 a new submission.  This item will be scheduled in the next
265                 sprint.  This process is repeated until there is no more
266                 feedback.  If feedback is received at the beginning of the sprint
267         you should respond to the feedback immediately to acknowledge that
268         it was received and if you will not be able to submit new patches
269         immediately let the maintainer know when you can.
270         \item[Step 4:] Once the code has been merged into the mainline master
271         branch, the "Merged" backlog item created in step 2 will be submitted
272         to the system test team for verification using the automated system
273         that the test code for that item is now passing.
274 \end{description}
276 \paragraph{}
277 Using the above steps until the code is merged into the mainline there will
278 always be open backlog items showing the outstanding work remaining.
280 \subsection{Product Owner Commitment}
281 \label{sec:product-owner-commitment}
283 \paragraph{}
284 It is important to note that the upstreaming effort will \textbf{NOT} work
285 without the commitment from the product owner to prioritize the upstream
286 tasks above all other tasks.  The product owner must understand the following:
288 \begin{itemize}
289         \item Once work has begun with the open source community to submit
290                 patches, that work must be given priority to be seen through to
291                 completion.  Failure to address feedback from the community in
292                 a timely manner will:
293                 \begin{itemize}
294                         \item Reduce credibility of developers in the open
295                                 source community.
296                         \item Delay the review of future submissions of the
297                                 patches.  After all, if the developer can't be
298                                 bothered to respond to feedback on their
299                                 patches why should others take time to give
300                                 that feedback.
301                 \end{itemize}
302         \item Any delay in submitting work to the upstream adds to the
303                 technical debt of the team in the following ways:
304                 \begin{itemize}
305                         \item If the architecture changes while waiting for the
306                                 work to be upstreamed then the effort spent to
307                                 develop that work is wasted and new effort must
308                                 be added to the technical debt of the team to
309                                 re-do the work based on the new architecture.
310                 \end{itemize}
311         \item As open source merge windows approach the priority of any
312                 outstanding upstreams must be increased.  The impact of missing
313                 a merge window can be huge due to:
314                 \begin{itemize}
315                         \item The LCPD commitment for a feature to be available in a
316                 given kernel version means that if we do not hit that kernel
317                 version we must carry the patches until at least the next
318                 kernel version.
319                         \item If the merge window missed happens to be for the
320                                 next LTS kernel then the feature will not be available on
321                 a long term kernel for at least a year.
322                 \end{itemize}
323 \end{itemize}
325 For the above reasons it is clear why the Product Owner \textbf{MUST} be
326 committed to upstream development and ensuring that priorities always reflect
327 this commitment.  While emergencies can happen that may delay an upstream
328 activity, it must always be with the knowledge in mind of the additional
329 technical debt incurred by the team.