Suggestions_for_services.md

   1 # Suggestions for Services
   2
   3 This document contains some suggestions on how to build frontend service
   4 files for this repository and how to contribute them. They do not cover what the
   5 [official documentation](https://web.obarun.org/software/66/latest/frontend.html) does,
   6 but are common sense rules for frontend building.
   7
   8 There is not one true way to build frontends as the format is quite flexible and
   9 different policies and preferences will result in different practices.
  10
  11 1. @execute scripts should be written in execline or sh. The former is preferred
  12 but not mandatory. When somebody writes in sh, they must take  [the differences
  13 expressed in the documentation](https://web.obarun.org/software/66/latest/frontend.html#A%20word%20about%20the%20@execute%20key) into account.
  14 2. @execute should contain the necessary setup and **only** the minimum command
  15 switches for the service to run (e.g. to keep it in the foreground).
  16 3. Every other switch should be under [environment] in *cmd_args* or other proper
  17 variables.
  18 4. *cmd_args* replaces *$OPTS* in scripts based on runit services.
  19 5. [stop] section replaces the *finish* script of runit services. Other than
  20 that, [stop] may be used only if  it is needed or it would substantially
  21 improve the service.
  22 6. Obarun frontend files are obviously a fantastic source of information. Please
  23 be aware that sometimes the policies and/or assumptions of obarun are very
  24 different than those of voidlinux.
  25 7. Do not include configuration file paths or change default configuration
  26 files with variables in [environment].
  27 8. Every new frontend service file is released originally with a @version value of 0.0.1 and
  28 is incremented in the following releases only if there a change.
  29 9. When using execline syntax in @execute, @build=auto may be ommited.
  30 10. Try to keep frontend service files compact, simple and easy to understand.
  31 A user can always customise them and put the customised version in /etc/66/service.
  32 11. Development happens in the _master_ branch. We create PRs against it, releases are tagged from it.