Merge 78e79e1d13 into 606e8490d3

docs/dev/basics.rst

@@ -28,7 +28,7 @@ rerun
 
 ::
 
-	make update
+  make update
 
 `make update` also applies the patches that can be found in the directories found in
 `patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
@@ -40,7 +40,7 @@ using
 
 ::
 
-	make update-patches
+  make update-patches
 
 If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
 and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
@@ -50,6 +50,7 @@ commits, making `git reflog` the only way to recover them!
 
 Development Guidelines
 ----------------------
+
 lua should be used instead of sh whenever sensible. The following criteria
 should be considered:
 
@@ -61,5 +62,71 @@ Code formatting may sound like a topic for the pedantic, however it helps if
 the code in the project is formatted in the same way. The following rules
 apply:
 
-- use tabs instead of spaces
+- use tabs instead of spaces (set your editor to show tabs as two spaces.) Only
+  exceptions are Makefiles, that need spaces in some places (for example the
+  Package definition)
 - trailing whitespaces must be eliminated
+
+Developing Packages
+-------------------
+
+If you want to develop your own external Gluon package, the best way would be 
+to start with an existing package from the gluon repository and adapt it, for 
+example use the package ``gluon-web-mesh-vpn-fastd`` as a base
+
+- rename all occurrences of your example package
+- adapt the upgrade script to your needs
+- to create new config values that may be editable with ``uci`` create a file 
+  in ``/ect/config/your_new_config`` with just one section
+
+::
+
+  config main 'settings'
+
+
+- to fill this section with values from the ``site.conf`` edit the upgrade 
+  script for your package and add the same section as the filename of the config
+  file in your ``site.conf``:
+
+::
+
+  your_new_config {
+    new_value = 'example'
+  }
+
+::
+
+Upgrading Packages from 2016.2.x
+--------------------------------
+
+The site.conf and external packages to be rewritten in some parts and Gluon now
+doesn't use LuCI for its Config Mode anymore, but our own fork
+"gluon-web", which is significantly smaller (as lots of features we don't
+need have been removed) for detailed changes see section `/web/`_.
+
+- the function ``gluon_luci.escape()`` must be replaced with ``pcdata()`` and
+  ``urlescape()`` with ``urlencode()``
+- the dependencies in the ``Makefile`` must be adapted: replace
+  ``DEPENDS:=gluon-luci-theme`` with ``DEPENDS:=gluon-web-theme``, ``luci-base``
+  with ``gluon-web`` and ``gluon-luci-admin`` with ``gluon-web-admin`` ...
+- ``i18n.translate()`` => ``translate()``
+- ``luci.template.render_string()`` =>
+  ``renderer.render_string()``
+- i.e. ``s:option(cbi.Value, "_altitude" ...`` =>
+  ``o = s:option(Value, "altitude" ...``
+- ``o.rmempty`` => ``o.optional``
+- adapt the paths: ``/lib/gluon/setup-mode/www`` =>
+  ``/lib/gluon/web/www``
+- includes: ``require 'luci.util'`` => ``require 'gluon.web.util'``, 'luci.i18n' and 'gluon.luci' => 'gluon.util'
+- ``local uci = luci.model.uci.cursor()`` => ``local uci = require("simple-uci").cursor()``
+- In ``site.mk`` all pakages with ``-luci-`` in its name must be replaced with
+  ``-web-`` (exception: ``gluon-luci-portconfig`` =>
+  ``gluon-web-network``
+- the Makefile now has to reside in a subfolder within the repository, all
+  files and folders needed for inclusion need to be in that same subfolder
+- the ``site.conf`` needs to be adjusted too. Refer to `site.html#configuration`_
+  for the new format:
+    - The changes in short: the ``fastd_mesh_vpn`` section has been renamed to
+      ``fastd`` and moved into a new section ``mesh_vpn``, with the exception of
+      the options ``enabled``, ``mtu`` and ``bandwidth_limit``, which are set
+      directly in the ``mesh_vpn`` section.

docs/dev/upgrade.rst

@@ -39,3 +39,5 @@ These are some guidelines for the script numbers:
 * ``5xx``: Miscellaneous (everything not fitting into any other category)
 * ``6xx`` .. ``8xx``: Currently unused
 * ``9xx``: Upgrade finalization
+
+Make sure all upgrade scripts are executable.