development.txt

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