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 In the past it was sometimes unclear when and how the community would reach its
  15 next release. Members were lacking in orientation and felt demotivated.
  16
  17 Another minor concern not yet analysed in depth was the expectation to show the
  18 public that the GNUnet project is still active and making progress. With an old
  19 release distributed by popular linux distributions it was hard to showcase
  20 people the GNUnet features and encourage to participate in the project.
  21
  22 To show people how the GNUnet project is releasing its software we hereby
  23 document the current release model:
  24
  25 * All main development (e.g. towards 0.12.x) continues on master.
  26 * Developers can continue to develop features in their own feature
  27   branches, but are encouraged to frequently merge into master (as long as they
  28   don't break the build) to avoid divergence and to detect issues from a
  29   merge/rebase early.
  30 * 0.11.x releases *must* be protocol-compatible to 0.11.0. So once
  31   master is NOT protocol-compatible to 0.11.0, development for 0.11.x
  32   must continue in an 0.11-branch where we only cherry-pick those
  33   changes from master that preserve protocol-compatibility.
  34 * better CI may allow us to detect breaking changes before merges in the future
  35   (but we shall never fault anybody for breaking stuff in master in non-obvious
  36   ways);
  37 * actual _release policy_:
  38   - tests must pass
  39   - no compiler warnings for -Wall
  40   - acceptance tests (manual feature test) must succeed
  41   - no known "release critical" bugs (where RC has no formal definition,
  42     mostly we rather explicitly declare certain bugs as "not critical")
  43   - Whenever API changes happen the person making that changes should update
  44     dependencies or at least work with people who hack on the dependencies to
  45     cooridnate the adjustments
  46   o buildbots are happy (if running)
  47   o static analysis is happy (if available, false-positives => ignore)
  48   o documentation is reasonably up-to-date
  49   + reasonable test coverage (if too terrible => move subsystem to experimental?)
  50   + texinfo (HTML+PDF) and doxygen happy? Ideally without warnings!
  51   + nobody screaming bloody murder because of almost-completed features/bugfixes
  52     almost ready to be merged?
  53   Legend: -: absolutely mandatory; o: important; +: nice to have
  54
  55
  56 For further information see: https://trunkbaseddevelopment.com/
  57
  58 II. Evaluation Criteria
  59 =======================
  60 (what are criterias to interprete the results as success if we review
  61 the problem and solution after a year or so)
  62
  63 III. Concerns (of team members)
  64 ===============================
  65 (if there are concerns of team members, write them down here to later
  66 review)
  67
  68 I disagree that "bugs tend to accumulate until they are not managable".
  69 The real issue is that neither writing testcases nor fixing bugs are
  70 fun tasks volunteers like to do. As you write yourself: you want a
  71 sense of achievement, recognition, "new features".  So as long as that
  72 is what you are motivated to do, you will not get stable, well-tested
  73 code. I don't have a magic bullet to motivate you to write more tests,
  74 or to improve existing tests. -CG
  75
  76   Your argument is good. Two or three of us thought that the problem is about
  77   missing releases which we feld demotivating. We thought, we were stucked
  78   somewhere. But as you state, it is us not doing the necessary work. What I
  79   still find useful is to document the release process. In consequence I
  80   changed the problem statement. -xrs
  81
  82 I also disagree that releases have to be 'known bug free'.  That bar is
  83 way too high. However, there are obviously 'critical' bugs, but what
  84 they are is another debate.  But not all bugs are critical. Also,
  85 I would distinguish between 'standard' and 'experimental' subsystems.
  86 Experimental subsystems should build. They don't have to run, or do
  87 anything useful. Not even tests have to pass for a release IMO. -CG
  88
  89   Thank you, I agree and changed it. -xrs
  90
  91 Git is also not a "release model".  Git is a software development
  92 tool.  But introducing branches in Git won't fix bugs. It also won't
  93 improve test coverage. It won't test the code on a broad range of
  94 platforms.  It also doubt it will give you the recognition you crave.
  95 More importantly, what you describe is already happening, and
  96 partially has contributed to the problems. Bart kept his own CADET
  97 hacks in his personal branch for years, hence without much feedback or
  98 review.  The secushare team kept their patches in their own branch,
  99 hence revealing interesting failure modes when it was finally merged.
 100 Martin kept some of his ABE-logic in his own branch (that one was
 101 merged without me noticing major problems).  Anyway, what you propose
 102 as Option 1 is already largely done, except that certain CI tasks
 103 simply cannot be productively done pre-merge right now (and I'm all
 104 for improving that situation). -CG
 105
 106   With resprect to changes kept in branches the reason why I personally keep
 107   changes back is because it takes very long for me to get something really
 108   working in C. Before that I either not worth it or I don't want to blame
 109   other before not being sure it's not my fault.
 110
 111   Can we track branches? Can we write a little cronjob that checks for branches
 112   that are to long undercover with the aim to recommend the responsible person
 113   to merge soon?
 114   - xrs
 115
 116 Finally, there is one last elephant with respect to branches and
 117 merging that I would like you to consider. Given that GNUnet is highly
 118 modular, you have largely benefited from the modular architecture and
 119 been able to hack in your respective corners, unaffected by other
 120 modules (modulo bugs in dependencies).  That is great, and the desired
 121 development mode.  It has the critical advantage that bugs in modules
 122 that nobody depends upon (auction, rps, social) can be in 'master' and
 123 won't disturb anything. As most new development usually happens on the
 124 leaves of the dependency graph, that is great.  However, occasionally
 125 there are architectural changes. Not of the type where the graph
 126 changes, but where key API assumptions change. We recently had one for
 127 the GNU Name System with the dropping of ".gnu".  Before, CADET
 128 changed the semantics and paramter for 'port'.  In the future, CORE
 129 will introduce protocol versioning.  Whenever such a change happens,
 130 it usually falls upon the person making that change to update
 131 dependencies as well (or at least to work with people who hack on the
 132 dependencies to coordinate the adjustments).  That way, changing an
 133 API for in-tree dependencies is a minor nuisance.  However, if
 134 branches exist, making sure that API changes do not break _any_ branch
 135 somewhere is impractical.  So at least at times where "major" API
 136 rewrites are happening, it is important to minimize the number of
 137 branches. -CG
 138
 139   Thank you for clarifying. I added the API aspect above. -xrs
 140
 141
 142 IV. Doing
 143 =========
 144 (who does what within which time frame?)
 145
 146 Let me list what I think needs doing:
 147
 148 1) Better CI setup: build on multiple platforms, build of
 149    "arbitrary" branches, reporting of regressions with
 150    decent diagnostics (!) to developers (not the crap
 151    Gitlab gives where I don't even easily get a stack
 152    trace on a core dump).
 153 2) A culture of fixing "other people"'s bugs: test case failures,
 154    portability issues, Mantis reports, all the non-sexy
 155    stuff.  Not the 'psycstore' was written by tg, so no
 156    need for !tg to try to fix it, or the "I use sqlite,
 157    why should I bother with postgres?"-crap I have heard
 158    too often.
 159 3) Improving test cases: better code coverage, more corner
 160    cases, complex deployment scenarios (NAT!), etc.;
 161    less manual testing by hand, more writing automated
 162    tests.
 163 4) There are also some bigger architectural changes ahead
 164    that I have mentioned in other places.  Without those,
 165    we won't be able to serve non-expert users.  So help
 166    with those would be welcome, but in terms of _process_
 167    I think 1-3 is what matters.
 168
 169 Note that none of this really adds up to a "release policy".
 170
 171   We should thing and talk about point 2 and 3 more in depth with the question
 172   in mind, how to make this task more attractive for the community :-)
 173
 174
 175 V. Previous Versions
 176 ====================
 177 (if we found some flaws in the solution, and we want to change the
 178 release policy, we document the old ones here als previous versions.
 179 the goal is establish a learn process.)
 180
 181 IV. References
 182 ==============
 183 (if there are references to paper, web pages and other sources.)