external/bsd/atf/dist/doc/roadmap.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
   3                   "http://docbook.org/xml/simple/1.1/sdocbook.dtd">
   4
   5 <article>
   6
   7 <articleinfo>
   8   <title>Rearchitecting ATF: Road trip to 1.0</title>
   9
  10   <author>
  11     <firstname>Julio</firstname>
  12     <surname>Merino</surname>
  13     <affiliation>
  14       <orgname>The NetBSD Foundation</orgname>
  15     </affiliation>
  16   </author>
  17 </articleinfo>
  18
  19 <section id="overview">
  20
  21 <title>Overview</title>
  22
  23 <para>This document describes the major steps to be taken before getting
  24 to the first stable release of ATF, 1.0.  Some of these steps describe
  25 the transition from the old code base to the new ideas documented in the
  26 specification (TODO: Add link somehow).</para>
  27
  28 </section>
  29
  30 <section id="plan-0-8">
  31
  32 <title>The plan to 0.8</title>
  33
  34 <itemizedlist>
  35
  36 <listitem><para>Add atf-sh interface to build-time tests.</para></listitem>
  37
  38 <listitem><para>Properly document the libraries: i.e. one page per
  39 module, detailed information of each function and type, etc.  At the
  40 very least atf-c.</para></listitem>
  41
  42 <listitem><para>Add a tool to collect multiple outputs of atf-run (from
  43 different machines) and generate a single (XML-only?) log with
  44 everything.  Must allow easy conversion to HTML for online
  45 publishing.</para></listitem>
  46
  47 <listitem><para>Allow grouping of test programs in tiers in an Atffile.
  48 This is to permit the user specify "dependencies" between test programs:
  49 e.g. do not run a specific test program if its dependencies have failed,
  50 because it will certainly fail also.</para></listitem>
  51
  52 <listitem><para>Provide a kernel-level unit testing API (for NetBSD
  53 only, at the moment).  This should come in the form of an atf.ko module
  54 that provides functions to define and register test cases, functions for
  55 results reporting and an interface (a trivial file system?) that
  56 transports the application/X-atf-tcs output to user-space, provides
  57 information to user-space about the available test cases (a list) and
  58 allows user-space to launch the execution of test
  59 cases.</para></listitem>
  60
  61 </itemizedlist>
  62
  63 </section>
  64
  65 <section id="plan-0-9">
  66
  67 <title>The plan to 0.9</title>
  68
  69 <itemizedlist>
  70
  71 <listitem><para>Add a module to atf-c to manage dynamic memory.  Should
  72 provide a "mem chunk" object that can only be managed through functions
  73 (i.e. not directly) so that access to buffers can be safely controlled.
  74 Dealing with strdup and similar functions, for example, might be
  75 complex.</para>
  76
  77 <para>See these old revisions for a start, but these did not work
  78 correctly because the use of (void **) casts brought aliasing
  79 problems:</para>
  80
  81 <para>78eeacf3b9284493e5e96b7866fc1d163a13bc02
  82 8e200683a2b70eadca728c2e0347d4790777b3fc
  83 872393ed0177cbcc30ffacede228eb3986c42ab7</para></listitem>
  84
  85 </itemizedlist>
  86
  87 </section>
  88
  89 <section id="plan-pre-1-0">
  90
  91 <title>The plan to 1.0 prereleases</title>
  92
  93 <itemizedlist>
  94
  95 <listitem><para>Fix all occurrences of XXX, TODO and
  96 FIXME.</para></listitem>
  97
  98 <listitem><para>Split the distfile into multiple components.  We should
  99 have a component for each language binding and a component providing the
 100 ATF tools, at the very least.  If we had this, external programs using
 101 ATF wouldn't need to depend on the tools and/or the C++ binding, because
 102 they could just require the user to build the atf-c
 103 binding.</para></listitem>
 104
 105 <listitem><para>Think of a way to properly add tests for (almost?) all
 106 error paths.  Most of them are probably broken
 107 already.</para></listitem>
 108
 109 <listitem><para>Improve error reporting: aside from clarifying error
 110 messages, this also implies adding more error cases to give them more
 111 semantic meaning at the source code level..</para></listitem>
 112
 113 <listitem><para>Make the shell library work with 'set
 114 -e'?</para></listitem>
 115
 116 <listitem><para>Shell test programs dynamically locate where the shell
 117 library is by calling atf-config (done by atf.init.subr).  Contrarywise,
 118 binary test programs are directly linked against the final location of
 119 libatf.  It may be nice if the latter loaded the library dynamically
 120 based on what atf-config said, so the user could switch atf
 121 installations by simply changing its PATH (and effectively making atf
 122 relocatable on the file system).  Why could this be nice?  To painlessly
 123 run an older atf test suite against a more recent version of the code
 124 base to ensure there are no regressions even with older tests.  Just a
 125 crazy idea, as maybe what the shell test programs currently do is
 126 stupid.</para></listitem>
 127
 128 <listitem><para>Allow users to customize the build of atf by defining
 129 additional meta-data for test cases.  At the moment this is possible
 130 because the meta-data is not sanity-checked, but I think it should be.
 131 Following the previous item, NetBSD could add a 'netbsd.pr' variable and
 132 then use this data when generating reports to add direct links to the
 133 appropriate PRs.</para></listitem>
 134
 135 <listitem><para>Make sure that the tests in tests/atf have, at the very
 136 least, the same coverage as the ones in
 137 tests/bootstrap.</para></listitem>
 138
 139 <listitem><para>Document the code.</para></listitem>
 140
 141 <listitem><para>Possibly add a way to automatically gain or drop
 142 privileges when require.user is set.</para></listitem>
 143
 144 <listitem><para>Add a way to specify which bug/issue/whatever a given
 145 test case is stress-testing.  This information is useful when detecting
 146 regressions.</para></listitem>
 147
 148 </itemizedlist>
 149
 150 </section>
 151
 152 <section id="plan-1.0-rc">
 153
 154 <title>The plan to 1.0 release candidates</title>
 155
 156 <itemizedlist>
 157
 158 <listitem><para>Build libatf as a shared library and set -version-info
 159 accordingly.</para></listitem>
 160
 161 <listitem><para>Set the DTDs' versions to 1.0.</para></listitem>
 162
 163 </itemizedlist>
 164
 165 </section>
 166
 167 <section id="plan-unknown">
 168
 169 <title>The plan to releases after 1.0</title>
 170
 171 <itemizedlist>
 172
 173 <listitem><para>Allow the parallel execution of tests.  Achieving this
 174 with a test program granularity is easy: only need to change atf-run.
 175 Lowering it to a finer granularity (test cases) is harder and maybe not
 176 worth it.</para></listitem>
 177
 178 </itemizedlist>
 179
 180 </section>
 181
 182 </article>