From f0f2d21562c376c5d35a92ddc0470998f53043f6 Mon Sep 17 00:00:00 2001 From: Johannes Keyser Date: Sun, 14 Jan 2018 22:30:30 +0100 Subject: [PATCH] doc: update HACKING, CONTRIBUTING and INSTALL information - use markdown more explicitly - update information on i18n and translation - move or delete redundant info from HACKING into CONTRIBUTING Signed-off-by: Johannes Keyser Reviewed-by: Sunil Mohan Adapa --- CONTRIBUTING.md | 8 ++- HACKING.md | 162 +++++++++++++++++++++++------------------------- INSTALL.md | 106 +++++++++++++++++-------------- 3 files changed, 144 insertions(+), 132 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43e02a77b..8a282094d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,4 @@ +# Contributing Here are some contributing guidelines for authors and reviewers of code changes. The goal is a readable log of code changes, to enhance transparency of their purpose and simplify debugging. Consider these guidelines as best practices, not @@ -19,8 +20,11 @@ Naming conventions: # For authors of patches * If you would like to contribute, but are unsure what to do, just ask. There - are usually also issues tagged as "beginners", which might be a good starting - point. + are usually also issues tagged as 'beginner', which might be a good starting + point to work on and have a known solution. Also, other developers are ready + to guide you on the implementation for such tasks. + Feel free to pickup a task from the issue by announcing it on the issue or by + creating a new issue for whatever task you are going to work on. * To get your changes included, you must open a pull request (PR), to get them reviewed. Briefly, fork the repository to your account, and edit, commit and push there. Then you can create a PR to the main repository. diff --git a/HACKING.md b/HACKING.md index 630ff7a4a..3df6ecb81 100644 --- a/HACKING.md +++ b/HACKING.md @@ -11,65 +11,76 @@ The entire setup is automatic and requires about 4.5 GB of disk space. 1. Install Vagrant and VirtualBox: + ``` $ sudo apt-get install virtualbox vagrant + ``` 2. To download, setup, run, and configure a VM for Plinth development using Vagrant, simply execute in your Plinth development folder: + ``` $ vagrant up + ``` 3. To access Plinth (from host), visit https://localhost:4430/plinth/ 4. Edit the source code in your host machine's Plinth development folder. - By default, this folder is shared within the VM, at /vagrant/. + By default, this folder is shared within the VM, at `/vagrant/`. To actually reflect the changes in the running VM, run on your host: + ``` $ vagrant provision + ``` ## Installing Dependencies Apart from dependencies listing in INSTALL.md file, Plinth may have additional dependencies required by modules of Plinth. To install these, run: - $ sudo apt install -y $(plinth --list-dependencies) +``` +$ sudo apt install -y $(plinth --list-dependencies) +``` ## Manually Setting Up for Development -It is recommended that you use Vagrant to setup your development -environment. However, for some reason, you wish setup manually, the -following tips will help: +It is recommended that you use Vagrant to setup your development environment. +However, for some reason, you wish setup manually, the following tips will help: -1. Instead of running "setup.py install" after every source modification, run +1. Instead of running `setup.py install` after every source modification, run the following command: - $ sudo python3 setup.py develop + ``` + $ sudo python3 setup.py develop + ``` - This will install the python package in a special development mode. Run it - normally. Any updates to the code (and core package data files) do not - require re-installation after every modification. + This will install the python package in a special development mode. Run it + normally. Any updates to the code (and core package data files) do not + require re-installation after every modification. - CherryPy web server also monitors changes to the source files and reloads - the server as soon as a file is modified. Hence it is usually sufficient - to modify the source and refresh the browser page to see the changes. + CherryPy web server also monitors changes to the source files and reloads + the server as soon as a file is modified. Hence it is usually sufficient + to modify the source and refresh the browser page to see the changes. 2. Plinth also support running without installing (as much as possible). Simply run it as: - $ sudo ./run --debug + ``` + $ sudo ./run --debug + ``` - In this mode, Plinth runs in working directory without need for - installation. It uses the plinth.conf config file in the working - directory if no regular config file (/etc/plinth/plinth.conf) is found. - It creates all that data and runtime files in data/var/*. + In this mode, Plinth runs in working directory without need for + installation. It uses the `plinth.conf` config file in the working + directory if no regular config file (`/etc/plinth/plinth.conf`) is found. + It creates all that data and runtime files in `data/var/*`. - *Note:* This mode is supported only in a limited manner. The following are - the unknown issues with it: + *Note:* This mode is supported only in a limited manner. The following are + the unknown issues with it: - 1. Help pages are also not built. Run 'make -C doc' manually. + 1. Help pages are also not built. Run `make -C doc` manually. - 2. Actions do not work when running as normal user without 'sudo' prefix. - You need to add 'actions' directory to be allowed for 'sudo' commands. - See data/etc/sudoers.d/plinth for a hint. + 2. Actions do not work when running as normal user without `sudo` prefix. + You need to add `actions` directory to be allowed for `sudo` commands. + See `data/etc/sudoers.d/plinth` for a hint. ### Testing Inside a Virtual Machine @@ -78,7 +89,7 @@ following tips will help: 2. Share the source folder and mount it on virtual machine. This could be done over NFS, SSH-fs or 'Shared Folders' feature on VirtualBox. -3. Run 'setup.py develop' or 'setup.py install' as described above on guest +3. Run `setup.py develop` or `setup.py install` as described above on guest machine. 4. Access the guest machine's Plinth web UI from host after setting bridging or @@ -86,37 +97,43 @@ following tips will help: ## Running Tests -1. Run tests: +To run tests: - $ python3 setup.py test +``` +$ python3 setup.py test +``` ## Running the Test Coverage Analysis -1. Run the coverage tool: +To run the coverage tool: - $ python3 setup.py test_coverage +``` +$ python3 setup.py test_coverage +``` - Invoking this command generates a binary-format '.coverage' data file in - the top-level project directory which is recreated with each run, and - writes a set of HTML and other supporting files which comprise the - browsable coverage report to the 'plinth/tests/coverage/report' directory. - Index.html presents the coverage summary, broken down by module. Data - columns can be sorted by clicking on the column header or by using mnemonic - hot-keys specified in the keyboard widget in the upper-right corner of the - page. Clicking on the name of a particular source file opens a page that - displays the contents of that file, with color-coding in the left margin to - indicate which statements or branches were executed via the tests (green) - and which statements or branches were not executed (red). +Invoking this command generates a binary-format `.coverage` data file in +the top-level project directory which is recreated with each run, and +writes a set of HTML and other supporting files which comprise the +browsable coverage report to the `plinth/tests/coverage/report` directory. +`Index.html` presents the coverage summary, broken down by module. Data +columns can be sorted by clicking on the column header or by using mnemonic +hot-keys specified in the keyboard widget in the upper-right corner of the +page. Clicking on the name of a particular source file opens a page that +displays the contents of that file, with color-coding in the left margin to +indicate which statements or branches were executed via the tests (green) +and which statements or branches were not executed (red). ## Building the Documentation Separately -Plinth man page is built from DocBook source in the doc/ directory. +Plinth man page is built from DocBook source in the `doc/` directory. FreedomBox manual is downloaded from the wiki is also available there. Both these are build during the installation process. -1. To build the documentation separately, run: +To build the documentation separately, run: - $ make -C doc +``` +$ make -C doc +``` ## Repository @@ -127,52 +144,29 @@ Plinth is available from [GitHub](https://github.com/freedombox/plinth). You can report bugs on Plinth's [issue tracker](https://github.com/freedombox/Plinth/issues). -For new developers looking to start contributing to the project, this -is a good place to pick up a task to work on. Tasks that are labeled -as 'beginner' are easy to work on and have a known solution. Also, -other developers are ready to guide you on the implementation for such -tasks. - -Feel free to pickup a task from the issue by announcing it on the -issue or by creating a new issue for whatever task you are going to -work on. - -## Submitting Your Changes - -Once you have completed implementing the solution, request a merge -into the upstream. - -Pacthes can be submitted in either of the two ways: - -- Post your patches to the FreedomBox discuss mailing list. Look at - Git documention on how to create submittable patches out of your - commits and post them to the list. - -- Create a pull request on Github. For information on placing a merge - request, consult GitHub documentation. - -## Coding Practices - -Plinth confirms to [PEP 8](http://www.python.org/dev/peps/pep-0008/) Python -coding standard. Before placing a merge request, you should check your code -for errors with *flake8* and indent your code with *yapf*. +See CONTRIBUTING.md for information how to best contribute code. ## Internationalization -Every module should `from gettext import gettext as _` and wrap -displayed strings with _(). We don't have the language stuff in place -yet (we have no translation files), but we need to put the -infrastructure in place for it from the start. Use it like this: +To mark text for translation, Plinth uses Django's translation strings. +A module should e.g. `from django.utils.translation import ugettext as _` +and wrap user-facing text with `_()`. Use it like this: - log.error(_("Couldn't import %s: %s"), path, e) +```python +message = _('Application successfully installed and configured.') +``` ## Translations -Introduce yourself on #freedombox IRC (irc.debian.org) and start translating -the PO file from your language directory from: -Plinth/plinth/locale/ -Introducing yourself is important since some work may have been done already -on Debian translators discussion lists and Weblate localization platform. -https://hosted.weblate.org/projects/freedombox/plinth/ -https://www.debian.org/MailingLists/subscribe +The easiest way to start translating is with your browser, by using +[Weblate](https://hosted.weblate.org/projects/freedombox/plinth/). +Your changes will automatically get pushed to the code repository. + +Alternatively, you can directly edit the `.po` file in your language directory +`Plinth/plinth/locale/` and create a pull request (see CONTRIBUTING.md). +In that case, consider introducing yourself on #freedombox IRC (irc.debian.org), +because some work may have been done already on the [Debian translators +discussion lists](https://www.debian.org/MailingLists/subscribe) +or the Weblate localization platform. + For more information on translations: https://wiki.debian.org/FreedomBox/Translate diff --git a/INSTALL.md b/INSTALL.md index ca9221267..d43347ea9 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,75 +2,89 @@ 1. Install the dependencies: - On a Debian based system, run: + On a Debian based system, run: - $ sudo apt-get install \ - augeas-tools \ - dblatex \ - docbook-utils \ - gettext \ - gir1.2-glib-2.0 \ - gir1.2-nm-1.0 \ - ldapscripts \ - libjs-bootstrap \ - libjs-jquery \ - libjs-modernizr \ - make \ - network-manager \ - ppp \ - pppoe \ - python3 \ - python3-apt \ - python3-augeas \ - python3-bootstrapform \ - python3-cherrypy3 \ - python3-configobj \ - python3-coverage \ - python3-django \ - python3-django-axes \ - python3-django-captcha \ - python3-django-stronghold \ - python3-gi \ - python3-psutil \ - python3-requests \ - python3-ruamel.yaml \ - python3-setuptools \ - xmlto + ``` + $ sudo apt-get install \ + augeas-tools \ + dblatex \ + docbook-utils \ + gettext \ + gir1.2-glib-2.0 \ + gir1.2-nm-1.0 \ + ldapscripts \ + libjs-bootstrap \ + libjs-jquery \ + libjs-modernizr \ + make \ + network-manager \ + ppp \ + pppoe \ + python3 \ + python3-apt \ + python3-augeas \ + python3-bootstrapform \ + python3-cherrypy3 \ + python3-configobj \ + python3-coverage \ + python3-django \ + python3-django-axes \ + python3-django-captcha \ + python3-django-stronghold \ + python3-gi \ + python3-psutil \ + python3-requests \ + python3-ruamel.yaml \ + python3-setuptools \ + xmlto + ``` 2. Install Plinth: - Unzip the source into a directory. Change to the directory containing the - program and run: + Unzip the source into a directory. Change to the directory containing the + program and run: - $ sudo python3 setup.py install - $ sudo apt install -y $(plinth --list-dependencies) + ``` + $ sudo python3 setup.py install + $ sudo apt install -y $(plinth --list-dependencies) + ``` 3. Run Plinth: - $ sudo plinth + ``` + $ sudo plinth + ``` 4. Access Plinth UI: - Plinth UI should be accessible at http://localhost:8000/plinth + Plinth UI should be accessible at http://localhost:8000/plinth # Note on Django version: Django 1.11 is required to run Plinth. You can check the version by running: - $ django-admin --version +``` +$ django-admin --version +``` -If apt-get provided django<1.11, then follow the steps below: +If apt-get provided django < 1.11, then follow the steps below: 1. Uninstall older django versions: - $ sudo apt-get remove python3-django python3-django-stronghold \ - python3-bootstrap + ``` + $ sudo apt-get remove python3-django python3-django-stronghold \ + python3-bootstrap + ``` 2. Install Python3 pip: - $ sudo apt-get install python3-pip + ``` + $ sudo apt-get install python3-pip + ``` 3. Install django1.11 through pip: - $ sudo pip3 install django django-bootstrap-form django-stronghold \ - django-axes django-simple-captcha --upgrade + ``` + $ sudo pip3 install django django-bootstrap-form django-stronghold \ + django-axes django-simple-captcha --upgrade + ```