gluon/docs/dev/basics.rst

Development Basics
==================

Gluon's source is kept in `git repositories`_ at GitHub.

.. _git repositories: https://github.com/freifunk-gluon

Bug Tracker
-----------

The `main repo`_ does have issues enabled. 

.. _main repo: https://github.com/freifunk-gluon/gluon

IRC
---

Gluon's developers frequent the IRC chatroom `#gluon`_ on `hackint`_.
There is a `webchat`_ that allows for easy access from within your
webbrowser. You're welcome to join us!

.. _#gluon: ircs://irc.hackint.org/#gluon
.. _hackint: https://hackint.org/
.. _webchat: https://webirc.hackint.org/#irc://irc.hackint.org/#gluon


Working with repositories
-------------------------

To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
rerun

::

  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`
can be referred to by the branch `base`.

After new patches have been committed on top of the `patched` branch (or existing commits
since the base commit have been edited or removed), the patch directories can be regenerated
using

::

  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.

Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
commits, making `git reflog` the only way to recover them!

::

  make refresh-patches

In order to refresh patches when updating feeds or the OpenWrt base, `make refresh-patches` applies and updates all of their patches without installing feed packages to the OpenWrt buildsystem.

This command speeds up the maintenance of updating OpenWrt and feeds.

Development Guidelines
----------------------
Lua should be used instead of sh whenever sensible. The following criteria
should be considered:

- Is the script doing more than just executing external commands? if so, use Lua
- Is the script parsing/editing json-data? If so, use Lua for speed
- When using sh, use jsonfilter instead of json_* functions for speed

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 basic rules
apply:

- use tabs instead of spaces
- trailing whitespaces must be eliminated
- files need to end with a final newline
- newlines need to have unix line endings (lf)

To that end we provide a ``.editorconfig`` configuration, which is supported by most
of the editors out there.

If you add Lua scripts to gluon, check formatting with ``luacheck``.
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00			`Development Basics`
			`==================`

			Gluon's source is kept in `git repositories`_ at GitHub.

			`.. _git repositories: https://github.com/freifunk-gluon`

			`Bug Tracker`
			`-----------`

			The `main repo`_ does have issues enabled.

			`.. _main repo: https://github.com/freifunk-gluon/gluon`

			`IRC`
			`---`

docs: improve references to the IRC chatroom (#1643) 2019-02-07 00:53:18 +00:00			Gluon's developers frequent the IRC chatroom `#gluon`_ on `hackint`_.
			There is a `webchat`_ that allows for easy access from within your
			`webbrowser. You're welcome to join us!`
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00
docs: improve references to the IRC chatroom (#1643) 2019-02-07 00:53:18 +00:00			`.. _#gluon: ircs://irc.hackint.org/#gluon`
			`.. _hackint: https://hackint.org/`
			`.. _webchat: https://webirc.hackint.org/#irc://irc.hackint.org/#gluon`
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00

			`Working with repositories`
			`-------------------------`

			To update the repositories used by Gluon, just adjust the commit IDs in `modules` and
			`rerun`

			`::`

docs: consistently indent .rst files with 2 spaces 2 spaces is the most common indentation width used in the docs; adjust the rest for consistency. Also change .editorconfig accordingly. 2021-12-24 13:16:04 +00:00			`make update`
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00
			`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`
docs: fix typos and common misspellings (#1668) 2019-03-10 19:15:25 +00:00			can be referred to by the branch `base`.
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00
docs: fix typos and common misspellings (#1668) 2019-03-10 19:15:25 +00:00			After new patches have been committed on top of the `patched` branch (or existing commits
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00			`since the base commit have been edited or removed), the patch directories can be regenerated`
			`using`

			`::`

docs: consistently indent .rst files with 2 spaces 2 spaces is the most common indentation width used in the docs; adjust the rest for consistency. Also change .editorconfig accordingly. 2021-12-24 13:16:04 +00:00			`make update-patches`
docs: move from README to docs/ 2014-07-09 10:43:10 +00:00
			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.

			Always call `make update-patches` after making changes to a module repository as `make update` will overwrite your
			commits, making `git reflog` the only way to recover them!
docs: add development guide including one first guideline wrt lua vs. sh usage (#951) 2016-11-29 19:45:25 +00:00
docs: add 'make refresh-patches' 2021-05-27 09:25:31 +00:00			`::`

docs: consistently indent .rst files with 2 spaces 2 spaces is the most common indentation width used in the docs; adjust the rest for consistency. Also change .editorconfig accordingly. 2021-12-24 13:16:04 +00:00			`make refresh-patches`
docs: add 'make refresh-patches' 2021-05-27 09:25:31 +00:00
			In order to refresh patches when updating feeds or the OpenWrt base, `make refresh-patches` applies and updates all of their patches without installing feed packages to the OpenWrt buildsystem.

			`This command speeds up the maintenance of updating OpenWrt and feeds.`

docs: add development guide including one first guideline wrt lua vs. sh usage (#951) 2016-11-29 19:45:25 +00:00			`Development Guidelines`
			`----------------------`
docs: Add information how to automatically check your code with luacheck 2019-06-24 02:41:02 +00:00			`Lua should be used instead of sh whenever sensible. The following criteria`
docs: add development guide including one first guideline wrt lua vs. sh usage (#951) 2016-11-29 19:45:25 +00:00			`should be considered:`

docs: Add information how to automatically check your code with luacheck 2019-06-24 02:41:02 +00:00			`- Is the script doing more than just executing external commands? if so, use Lua`
			`- Is the script parsing/editing json-data? If so, use Lua for speed`
docs: dev/basics: add rules for coding guide (#970) * use tabs instead of spaces * use jsonfilter for speed 2016-12-08 22:56:43 +00:00			`- When using sh, use jsonfilter instead of json_* functions for speed`
docs: add development guide including one first guideline wrt lua vs. sh usage (#951) 2016-11-29 19:45:25 +00:00
docs: dev/basics: add rules for coding guide (#970) * use tabs instead of spaces * use jsonfilter for speed 2016-12-08 22:56:43 +00:00			`Code formatting may sound like a topic for the pedantic, however it helps if`
docs: Add information how to automatically check your code with luacheck 2019-06-24 02:41:02 +00:00			`the code in the project is formatted in the same way. The following basic rules`
docs: dev/basics: add rules for coding guide (#970) * use tabs instead of spaces * use jsonfilter for speed 2016-12-08 22:56:43 +00:00			`apply:`

			`- use tabs instead of spaces`
			`- trailing whitespaces must be eliminated`
add .editorconfig (#1951) Resolves #1929 2020-03-08 18:18:17 +00:00			`- files need to end with a final newline`
			`- newlines need to have unix line endings (lf)`

			To that end we provide a ``.editorconfig`` configuration, which is supported by most
			`of the editors out there.`
docs: Add information how to automatically check your code with luacheck 2019-06-24 02:41:02 +00:00
			If you add Lua scripts to gluon, check formatting with ``luacheck``.