development.txt

   1 ---
   2 ---
   3 Development
   4 ===========
   5
   6 include::menu.inc[]
   7
   8 == The Source Code
   9
  10 The LEDE project source code starts off with OpenWrt revision r49258. The code
  11 is stored inside a git tree which contains all branches and releases ever made
  12 by OpenWrt. While importing the sources the tree was normalised and some
  13 minor tweaks were made to committer names and mail addresses.
  14
  15 All repositories can be browsed online through
  16 http://git.lede-project.org/[Gitweb] as well.
  17
  18 === Getting The _LEDE_ Code
  19
  20 Any _LEDE_ development happens in the main +source.git+ repository which is
  21 accessible via both HTTP and HTTPS:
  22
  23 ----
  24 git clone http://git.lede-project.org/source.git
  25 ----
  26
  27 You can find a mirror of the repository on Github:
  28
  29 ----
  30 git clone https://github.com/lede-project/source.git
  31 ----
  32
  33 === Getting the OpenWrt Code
  34
  35 We keep the original OpenWrt source code up to
  36 https://git.lede-project.org/?p=openwrt/source.git;a=commit;h=ee53a240ac902dc83209008a2671e7fdcf55957a[r49258]
  37 available, mostly as reference and for historic interest.
  38
  39 The original OpenWrt Subversion repository has been split up into several Git
  40 repositories mapping the various SVN directories and tags to proper Git
  41 branches.
  42
  43 ----
  44 git clone http://git.lede-project.org/openwrt/source.git
  45 git clone http://git.lede-project.org/openwrt/packages.git
  46 git clone http://git.lede-project.org/openwrt/feeds.git
  47 git clone http://git.lede-project.org/openwrt/docs.git
  48 ----
  49
  50 === The Web Presence
  51
  52 The pages you're reading are generated from text files using the
  53 http://www.methods.co.nz/asciidoc/[AsciiDoc] suite. Any changes made to the
  54 projects web site will be reflected in our +web.git+ repository:
  55
  56 ----
  57 git clone http://git.lede-project.org/web.git
  58 ----
  59
  60 === Submitting Patches
  61
  62 The biggest difference is that we now accept pull requests. The tree that shall
  63 be pulled from needs to be hosted publicly. Small fixes and minor patches can
  64 also be submitted via the
  65 http://lists.infradead.org/mailman/listinfo/lede-dev[development mailing list].
  66 Submissions should follow these rules
  67
  68 . TBD
  69
  70 All patches need to be sent in a format that they are listed in http://patchwork.ozlabs.org/project/lede/list/[patchwork].
  71 If the patch does not get listed in patchwork then it won't get processed.
  72
  73
  74 === Reporting Bugs
  75
  76 . *All* bug reports need to be submitted via the
  77   http://lists.infradead.org/mailman/listinfo/lede-dev[development mailing list]
  78 . When reporting bugs please make sure to
  79   .. Name the tree/revision
  80   .. Name the affected device
  81   .. What does it do that it should not do / what does it not do that it should do
  82   .. Steps to reproduce
  83   .. What you have already done to fix the problem
  84   .. Any additional info you thinks is important
  85 . Reporting a bug means that you reported a bug. It does not constitute a claim that
  86   anyone has to work on fixing it.
  87 . Pointless/vague/silly/... bugs reports will be ignored
  88 . Feature requests are not Bugs. They will also be ignored.
  89 . The better your bug report, the more likely it is that it will be worked on.
  90
  91 All bug reports need to be sent in a format so that they are listed in the issue
  92 tracker (__LINK__). If the bug report does not get listed in the issue tracker then
  93 it won't get processed.
  94
  95
  96 === Patch Merging And Tree Life Cycle
  97
  98 We encourage committers to host their own staging trees where they aggregate patches
  99 that they feel responsible for and/or ones that they created themselves. Once the tree
 100 has been reviewed and tested it can be proposed for inclusion in the master branch.
 101
 102 . Trees will be merged into master at any time
 103 . Bug fixes can be merged into master directly
 104 . PRs can be sent to the patches mailing list from any source and will always be considered
 105   for inclusion if the quality of the tree is good and format of submission is correct
 106 . Staging trees can be hosted as part of the projects git infrastucture, private servers, ...
 107
 108 === Kernel updates
 109
 110 It has proven impractical and a time killer to always be on the very latest kernel within
 111 2 days of its release. It has caused these issues.
 112
 113 . diversification of kernel versions
 114 . pressure on maintainers to constantly upgrade rather than stabilise
 115 . huge effort invested to upgrade 3-4 times between releases
 116 . huge workload to maintain kmod-* packaging
 117 . Upgrade to kernels that might not be fully tested
 118
 119 This is obviously not an invite to sit on ancient and dusty kernels. A sane path in between
 120 should be taken that give the community recent kernels without causing unnecessary workload
 121 and stability issues.
 122
 123 There should be a max of three concurrent kernel version. Having only two concurrent versions
 124 is better than three.
 125
 126 In Short - stability should be valued higher than bleeding edge, although bleeding edge is
 127 also important, but not as a trade-off to stability.
 128
 129
 130 === Releases
 131
 132 Generating Releases has already been vastly automated. The remaining parts of the process need
 133 to also be automated before the first _LEDE_ release. We will introduce a TESTERS file that is
 134 formatted similarly to the MAINTAINERS file of the kernel. Community members can list themselves
 135 as testers for a target/profile/device. Once a release has been generated testers should receive
 136 an email informing them of the requirement for images to be tested. It needs to be decided if only
 137 tested images should be included in the binary release.
 138
 139 Releases should
 140
 141 . Happen at least once a year
 142 . Have at least one maintenance update
 143 . Provide CVE/critical/... fixes for at least one year after the release
 144 . Only include maintained targets
 145 . Only include targets that have seen on device testing
 146 . Be ready when they are ready
 147
 148 See the TODO page for more info.