sandbox/proposal_regressiontestframwork.moin

   1 ## This will eventually do to wiki.debian.org/RegressionTestFramework
   2
   3  * '''Created''': <<Date(2010-10-07)>>
   4  * '''Contributors''': NeuroDebian
   5  * '''Packages affected''':
   6  * '''See also''':
   7
   8 == Summary ==
   9
  10 This specification describes the way we would like Debian specifications to be
  11 written. It takes the form of a specification itself.
  12
  13 == Rationale ==
  14
  15 As we develop new ideas for features in Debian, it's important to be able to
  16 communicate them clearly. This serves the purpose of making it clear what the
  17 feature is about, and allowing people to evolve an implementation strategy for
  18 it.
  19
  20 Publishing this content gives our community a chance to participate in the
  21 discussion and design of a feature, and increases the chance that community
  22 members will feel confident enough to start work on the implementation of the
  23 feature.
  24
  25 A good specification also allows community members who were not physically
  26 present at meetings discussing a topic to participate in the implementation of
  27 the spec.
  28
  29 Bottom line: the better your spec, the better the chances that your ideas will
  30 clearly understood by every contributor that might help.
  31
  32 == Use Cases ==
  33
  34   * Bob is the maintainer for the boot process for Debian. In the etch cycle,
  35     he would like to work on getting the boot time down to two seconds from
  36     boot manager to GDM screen. He creates an entry for the specification in the
  37     wiki, discusses it at debconf, and starts writing out a braindump of it.
  38
  39   * Arnaud is a student participating in Google's Summer of code and wants to
  40     make sure that his project fits the short description that has been given
  41     on the ideas page. He writes a detailed spec in the wiki. His mentor can
  42     then confirm that he's on good track. The specification is published on a
  43     mailing list and people's comments help improve it even further.
  44
  45 == Scope ==
  46
  47 This specification covers feature specifications for Debian. It is not meant as
  48 a more general specification format.
  49
  50 == Design ==
  51
  52 A specification should be built with the following considerations:
  53
  54   * The person implementing it may not be the person writing it. It should be
  55   * clear enough for someone to be able to read it and have a clear path
  56   * towards implementing it. If it doesn't, it needs more detail.
  57
  58   * That the use cases covered in the specification should be practical
  59   * situations, not contrived issues.
  60
  61   * Limitations and issues discovered during the creation of a specification
  62   * should be clearly pointed out so that they can be dealt with explicitly.
  63
  64   * If you don't know enough to be able to competently write a spec, you should
  65   * either get help or research the problem further. Avoid spending time making
  66   * up a solution: base yourself on your peers' opinions and prior work.
  67
  68 Specific issues related to particular sections are described further below.
  69
  70 === Summary ===
  71
  72 The summary should not attempt to say '''why''' the spec is being defined, just
  73 '''what''' is being specified.
  74
  75 === Rationale ===
  76
  77 This should be the description of '''why''' this spec is being defined.
  78
  79 === Scope and Use Cases ===
  80
  81 While not always required, but in many cases they bring much better clarity to
  82 the scope and scale of the specification than could be obtained by talking in
  83 abstract terms.
  84
  85 === Implementation Plan ===
  86
  87 This section is usually broken down into subsections, such as the packages
  88 being affected, data and system migration where necessary, user interface
  89 requirements and pictures     (photographs of drawings on paper work well).
  90
  91 == Implementation ==
  92
  93 To implement a specification, the developer should observe the use cases
  94 carefully, and follow the design specified. He should make note of places in
  95 which he has strayed from the design section, adding rationale describing why
  96 this happened. This is important so that next iterations of this specification
  97 (and new specifications that touch upon this subject) can use the specification
  98 as a reference.
  99
 100 The implementation is very dependent on the type of feature to be implemented.
 101 Refer to the team leader for further suggestions and guidance on this topic.
 102
 103 == Outstanding Issues ==
 104
 105 The specification process requires experienced people to drive it. More
 106 documentation on the process should be produced.
 107
 108 The drafting of a specification requires english skills and a very good
 109 understanding of the problem. It must also describe things to an extent that
 110 someone else could implement. This is a difficult set of conditions to ensure
 111 throughout all the specifications added.
 112
 113 There is a lot of difficulty in gardening obsolete, unwanted and abandoned
 114 specifications in the Wiki.
 115
 116 == BoF agenda and discussion ==
 117
 118 Possible meetings where this specification will be discussed.
 119 ----
 120 CategorySpec
 121