doc/release_policy.rfc.txt

   1 ***********************************************************************
   2 ********************* Release Policy (RFC) ****************************
   3 ***********************************************************************
   4
   5 We suggest this structure of the proposal document as part of a tiny
   6 social process in order to find a decision in a cooperativ and common
   7 way.
   8
   9
  10 I. Driver
  11 =========
  12 (What is the problem and what solution did we find?)
  13
  14 The problem for the GNUnet community stated here is how to evolve the
  15 GNUnet team and code organization, so that developing code gets
  16 attractive again and using GNUnet for testing purposes or even for some
  17 little usecases becomes easier. In the current organizational model
  18 bugs tend to accumulate until they are not managable or overwhelming,
  19 however, it's clear, that every release candidate should be free from
  20 known bugs. There is more. Devs and user need to feel progress to have
  21 "Erfolgserlebnisse" (roughly: "sense of achievement") and recognition,
  22 like a new release, a "product" they have contributed to, listing new
  23 features with short description of amazing privacy preserving use cases.
  24
  25 A possible solution to this problem might be a new and lightweighted
  26 release model with git.
  27
  28 Release Models with git:
  29
  30 Option 1:
  31   * code organization and branching
  32     * master branch is release branch, tagged with different version
  33       numbers development occurs in little side branches
  34     * mature code resides in a staging branch for testing and quality
  35       management
  36   * release process
  37     * development in little side branches
  38     * if code is mature, merge with staging branch and do testing,
  39     * static/dynamic analysis and code audits if checks are okay, merge
  40       with release branch and tag with new version number
  41
  42 Option 2:
  43   * code organization and branching
  44     * master branch is development branch
  45     * further development task can be done in other side branches
  46       for every release candidate exists a new branch called after the
  47       version number
  48   * release process
  49     * development in master and side branches
  50     * if code of side branches is mature merge with master branch
  51     * if code in master branch is mature, create if not existant a new
  52     * release branch called after the new version number and merge with
  53       master
  54     * in the release branch do testing, static/dynamic analysis
  55       and code audits
  56     * if checks are okay, tag as release candidate
  57
  58
  59 Option 3: (What we really do right now)
  60 * changes that are not expected/known to break anything go into master;
  61   we may be wrong, better CI may allow us to detect breaking changes
  62   before merges in the future (but we shall never fault anybody for
  63   breaking stuff in master in non-obvious ways);
  64 * experimental development happens in branches, created by individuals
  65   or groups as they see fit. They are encouraged to merge often (if that
  66   would not break anything) to avoid divergence and to detect issues from
  67   a merge/rebase early.
  68 * actual _release policy_:
  69   - tests must pass
  70   - no compiler warnings for -Wall
  71   - acceptance tests (manual feature test) must succeed
  72   - no known "release critical" bugs (where RC has no formal definition,
  73     mostly we rather explicitly declare certain bugs as "not critical")
  74   o buildbots are happy (if running)
  75   o static analysis is happy (if available, false-positives => ignore)
  76   o documentation is reasonably up-to-date
  77   + reasonable test coverage (if too terrible => move subsystem to experimental?)
  78   + texinfo (HTML+PDF) and doxygen happy? Ideally without warnings!
  79   + nobody screaming bloody murder because of almost-completed features/bugfixes
  80     almost ready to be merged?
  81   Legend: -: absolutely mandatory; o: important; +: nice to have
  82
  83 ...
  84
  85 Option 1 and 2 are two flavours describe in
  86 https://trunkbaseddevelopment.com/
  87
  88 II. Evaluation Criteria
  89 =======================
  90 (what are criterias to interprete the results as success if we review
  91 the problem and solution after a year or so)
  92
  93 III. Concerns (of team members)
  94 ===============================
  95 (if there are concerns of team members, write them down here to later
  96 review)
  97
  98 I disagree that "bugs tend to accumulate until they are not managable".
  99 The real issue is that neither writing testcases nor fixing bugs are
 100 fun tasks volunteers like to do. As you write yourself: you want a
 101 sense of achievement, recognition, "new features".  So as long as that
 102 is what you are motivated to do, you will not get stable, well-tested
 103 code. I don't have a magic bullet to motivate you to write more tests,
 104 or to improve existing tests. -CG
 105
 106 I also disagree that releases have to be 'known bug free'.  That bar is
 107 way too high. However, there are obviously 'critical' bugs, but what
 108 they are is another debate.  But not all bugs are critical. Also,
 109 I would distinguish between 'standard' and 'experimental' subsystems.
 110 Experimental subsystems should build. They don't have to run, or do
 111 anything useful. Not even tests have to pass for a release IMO. -CG
 112
 113 Git is also not a "release model".  Git is a software development
 114 tool.  But introducing branches in Git won't fix bugs. It also won't
 115 improve test coverage. It won't test the code on a broad range of
 116 platforms.  It also doubt it will give you the recognition you crave.
 117 More importantly, what you describe is already happening, and
 118 partially has contributed to the problems. Bart kept his own CADET
 119 hacks in his personal branch for years, hence without much feedback or
 120 review.  The secushare team kept their patches in their own branch,
 121 hence revealing interesting failure modes when it was finally merged.
 122 Martin kept some of his ABE-logic in his own branch (that one was
 123 merged without me noticing major problems).  Anyway, what you propose
 124 as Option 1 is already largely done, except that certain CI tasks
 125 simply cannot be productively done pre-merge right now (and I'm all
 126 for improving that situation). -CG
 127
 128 Finally, there is one last elephant with respect to branches and
 129 merging that I would like you to consider. Given that GNUnet is highly
 130 modular, you have largely benefited from the modular architecture and
 131 been able to hack in your respective corners, unaffected by other
 132 modules (modulo bugs in dependencies).  That is great, and the desired
 133 development mode.  It has the critical advantage that bugs in modules
 134 that nobody depends upon (auction, rps, social) can be in 'master' and
 135 won't disturb anything. As most new development usually happens on the
 136 leaves of the dependency graph, that is great.  However, occasionally
 137 there are architectural changes. Not of the type where the graph
 138 changes, but where key API assumptions change. We recently had one for
 139 the GNU Name System with the dropping of ".gnu".  Before, CADET
 140 changed the semantics and paramter for 'port'.  In the future, CORE
 141 will introduce protocol versioning.  Whenever such a change happens,
 142 it usually falls upon the person making that change to update
 143 dependencies as well (or at least to work with people who hack on the
 144 dependencies to coordinate the adjustments).  That way, changing an
 145 API for in-tree dependencies is a minor nuisance.  However, if
 146 branches exist, making sure that API changes do not break _any_ branch
 147 somewhere is impractical.  So at least at times where "major" API
 148 rewrites are happening, it is important to minimize the number of
 149 branches. -CG
 150
 151
 152 IV. Doing
 153 =========
 154 (who does what within which time frame?)
 155
 156 Let me list what I think needs doing:
 157
 158 1) Better CI setup: build on multiple platforms, build of
 159    "arbitrary" branches, reporting of regressions with
 160    decent diagnostics (!) to developers (not the crap
 161    Gitlab gives where I don't even easily get a stack
 162    trace on a core dump).
 163 2) A culture of fixing "other people"'s bugs: test case failures,
 164    portability issues, Mantis reports, all the non-sexy
 165    stuff.  Not the 'psycstore' was written by tg, so no
 166    need for !tg to try to fix it, or the "I use sqlite,
 167    why should I bother with postgres?"-crap I have heard
 168    too often.
 169 3) Improving test cases: better code coverage, more corner
 170    cases, complex deployment scenarios (NAT!), etc.;
 171    less manual testing by hand, more writing automated
 172    tests.
 173 4) There are also some bigger architectural changes ahead
 174    that I have mentioned in other places.  Without those,
 175    we won't be able to serve non-expert users.  So help
 176    with those would be welcome, but in terms of _process_
 177    I think 1-3 is what matters.
 178
 179 Note that none of this really adds up to a "release policy".
 180
 181
 182 V. Previous Versions
 183 ====================
 184 (if we found some flaws in the solution, and we want to change the
 185 release policy, we document the old ones here als previous versions.
 186 the goal is establish a learn process.)
 187
 188 IV. References
 189 ==============
 190 (if there are references to paper, web pages and other sources.)