2
0

release_policy.rfc.txt 8.6 KB

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