mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
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 <johanneskeyser@posteo.de> Reviewed-by: Sunil Mohan Adapa <sunil@medhas.org>
This commit is contained in:
Johannes Keyser
Sunil Mohan Adapa
parent
1779ac8928
commit
f0f2d21562
@ -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.
|
||||
|
||||
162
HACKING.md
162
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
|
||||
|
||||
106
INSTALL.md
106
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
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user