sandbox/proposal_regressiontestframwork.moin

   1 ## This will eventually do to wiki.debian.org/RegressionTestFramework
   2
   3  * '''Created''': <<Date(2010-10-07)>>
   4  * '''Contributors''': MichaelHanke
   5  * '''Packages affected''':
   6  * '''See also''':
   7
   8 == Summary ==
   9
  10 This specification describes conventions and tools that allow Debian to
  11 distribute and run regression test batteries developed by upstream or
  12 Debian developers in a uniform fashion.
  13
  14 == Rationale ==
  15
  16 Ideally software packaged for Debian comes with an exhaustive test suite that
  17 can be used to determine whether this software works as expected on the Debian
  18 platform. However, especially for complex software, these test suites are often
  19 resource hungry (CPU time, memory, diskspace, network bandwidth) and cannot be
  20 ran at package build time by buildds. Consequently, test suites are only
  21 utilized by the packager on a particular machine, before uploading a new version
  22 to the archive.
  23
  24 However, Debian is an integrated system and packaged software is typically made
  25 to rely on functionality provided by other Debian packages (e.g. shared
  26 libraries) instead of shipping duplicates with different versions in every
  27 package -- for many good reasons. Unfortunately, there is also a downside to
  28 this: Debian packages often use 3rd-party tools with different versions than
  29 those tested by upstream, and moreover, the actual versions might change
  30 frequently between to subsequent uploads of a package.  Currently a change in a
  31 dependency that introduces an incompatibility cannot be detected reliably
  32 (before users have filed a bug report) -- even if upstream provides a testsuite
  33 that would have caught the breakage. Although there are archive-wide QA efforts
  34 (e.g. constantly rebuilding all packages) these tests can only detect API/ABI
  35 breakage or functionality tested during build-time checks -- they are not
  36 exhaustive for the aforementioned reasons.
  37
  38 This is a proposal to, first of all, package upstream test suites in a way that
  39 they can be used to run expensive archive-wide QA tests. However, this is also
  40 a proposal to establish means to test interactions of software from multiple
  41 Debian packages and test proper, continued, integration into the Debian system.
  42
  43 == Use Cases ==
  44
  45   * Bob is the maintainer for the boot process for Debian. In the etch cycle,
  46     he would like to work on getting the boot time down to two seconds from
  47     boot manager to GDM screen. He creates an entry for the specification in the
  48     wiki, discusses it at debconf, and starts writing out a braindump of it.
  49
  50   * Arnaud is a student participating in Google's Summer of code and wants to
  51     make sure that his project fits the short description that has been given
  52     on the ideas page. He writes a detailed spec in the wiki. His mentor can
  53     then confirm that he's on good track. The specification is published on a
  54     mailing list and people's comments help improve it even further.
  55
  56 == Scope ==
  57
  58 This specification covers feature specifications for Debian. It is not meant as
  59 a more general specification format.
  60
  61 == Design ==
  62
  63 A specification should be built with the following considerations:
  64
  65   * The person implementing it may not be the person writing it. It should be
  66   * clear enough for someone to be able to read it and have a clear path
  67   * towards implementing it. If it doesn't, it needs more detail.
  68
  69   * That the use cases covered in the specification should be practical
  70   * situations, not contrived issues.
  71
  72   * Limitations and issues discovered during the creation of a specification
  73   * should be clearly pointed out so that they can be dealt with explicitly.
  74
  75   * If you don't know enough to be able to competently write a spec, you should
  76   * either get help or research the problem further. Avoid spending time making
  77   * up a solution: base yourself on your peers' opinions and prior work.
  78
  79 Specific issues related to particular sections are described further below.
  80
  81 === Summary ===
  82
  83 The summary should not attempt to say '''why''' the spec is being defined, just
  84 '''what''' is being specified.
  85
  86 === Rationale ===
  87
  88 This should be the description of '''why''' this spec is being defined.
  89
  90 === Scope and Use Cases ===
  91
  92 While not always required, but in many cases they bring much better clarity to
  93 the scope and scale of the specification than could be obtained by talking in
  94 abstract terms.
  95
  96 === Implementation Plan ===
  97
  98 This section is usually broken down into subsections, such as the packages
  99 being affected, data and system migration where necessary, user interface
 100 requirements and pictures     (photographs of drawings on paper work well).
 101
 102 == Implementation ==
 103
 104 To implement a specification, the developer should observe the use cases
 105 carefully, and follow the design specified. He should make note of places in
 106 which he has strayed from the design section, adding rationale describing why
 107 this happened. This is important so that next iterations of this specification
 108 (and new specifications that touch upon this subject) can use the specification
 109 as a reference.
 110
 111 The implementation is very dependent on the type of feature to be implemented.
 112 Refer to the team leader for further suggestions and guidance on this topic.
 113
 114 == Outstanding Issues ==
 115
 116 The specification process requires experienced people to drive it. More
 117 documentation on the process should be produced.
 118
 119 The drafting of a specification requires english skills and a very good
 120 understanding of the problem. It must also describe things to an extent that
 121 someone else could implement. This is a difficult set of conditions to ensure
 122 throughout all the specifications added.
 123
 124 There is a lot of difficulty in gardening obsolete, unwanted and abandoned
 125 specifications in the Wiki.
 126
 127 == BoF agenda and discussion ==
 128
 129 Possible meetings where this specification will be discussed.
 130 ----
 131 CategorySpec
 132