nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-09-19 04:59:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

HACKING.md: Re-organised contents according to onboarding journey

Browse Source 
See MR#1919.note_194567.

Since the documents and some chapters are long a table of contents has been
added at the beginning along with navigation links pointing back to it at the
end of main sections and long chapters.

Signed-off-by: Fioddor Superconcentrado <fioddor@gmail.com>
[sunil: Drop periods at the end of TOC entries]
[sunil: Re-title some sections]
[sunil: Add links to Django i18n documentation and IRC chatroom]
Signed-off-by: Sunil Mohan Adapa <sunil@medhas.org>
Reviewed-by: Sunil Mohan Adapa <sunil@medhas.org>
This commit is contained in:
Fioddor Superconcentrado 2020-09-26 12:59:14 +02:00 committed by Sunil Mohan Adapa
parent fe183dbc72
commit 6bb5d34132
No known key found for this signature in database
GPG Key ID: 43EA1CFF0AA7C5F2
1 changed files with 122 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
HACKING.md
View File

@ -1,6 +1,30 @@
# Hacking # Hacking
## Requirements for Development OS This document provides reference information for FreedomBox **contribution** hacking **procedures**:
1. [Picking a task to work on](#picking-a-task-to-work-on)
1. [Setting up and using development environments](#development-environments-setting-up-and-their-usage)
1. [Contributing translations + how to make/keep FreedomBox international](#makingkeeping-freedombox-international)
1. [Testing](#testing)
1. [Building user documentation](#building-the-user-documentation-separately)
1. [Submitting your changes](#submitting-your-changes)
1. [Other related stuff](#miscelanea)
It doesn't cover arquitecture, design choices, or other product internals.
## Picking a task to work on
You can report bugs on FreedomBox Service's (Plinth's) [issue
tracker](https://salsa.debian.org/freedombox-team/freedombox/issues).
Newcomers will find easy, self-contained tasks tagged as "beginner".
Source code for FreedomBox Service is available from
[salsa.debian.org](https://salsa.debian.org/freedombox-team/freedombox).
## Development environments: setting up and their usage
### Requirements for Development OS
FreedomBox is built as part of Debian GNU/Linux. However, you don't need to FreedomBox is built as part of Debian GNU/Linux. However, you don't need to
install Debian to do development for FreedomBox. FreedomBox development is install Debian to do development for FreedomBox. FreedomBox development is
@ -21,7 +45,7 @@ In addition:
- You need Mumble voice chat software to participate in bi-weekly live - You need Mumble voice chat software to participate in bi-weekly live
development discussions. development discussions.
## Using Containers ### Using Containers
The `./container` script shipped with FreedomBox source code can manage the The `./container` script shipped with FreedomBox source code can manage the
development environment inside a systemd-nspawn container. development environment inside a systemd-nspawn container.
@ -53,7 +77,7 @@ development environment inside a systemd-nspawn container.
host$ ./container ssh host$ ./container ssh
``` ```
### Using after Setup #### Using after Setup
After logging into the container, the source code is available in `/freedombox` After logging into the container, the source code is available in `/freedombox`
directory: directory:
@ -81,7 +105,7 @@ guest$ sudo ./setup.py install
Note: This development container has automatic upgrades disabled by default. Note: This development container has automatic upgrades disabled by default.
### Troubleshooting #### Troubleshooting
* Sometimes `host$ ./container destroy && ./container up` doesn't work. In such * Sometimes `host$ ./container destroy && ./container up` doesn't work. In such
cases, try to delete the hidden `.container` folder and then `host$ cases, try to delete the hidden `.container` folder and then `host$
@ -89,13 +113,17 @@ Note: This development container has automatic upgrades disabled by default.
* Not all kinds of changes are automatically updated. Try `guest$ sudo mount -o * Not all kinds of changes are automatically updated. Try `guest$ sudo mount -o
remount /freedombox`. remount /freedombox`.
## Using Vagrant
[back to index](#hacking)
### Using Vagrant
Use VirtualBox and Vagrant if for some reason the container option is not Use VirtualBox and Vagrant if for some reason the container option is not
suitable, such as when you are running non-GNU/Linux machine or a non-systemd suitable, such as when you are running non-GNU/Linux machine or a non-systemd
machine. machine.
### For Debian GNU/Linux and Derivatives #### For Debian GNU/Linux and Derivatives
1. Install Git, Vagrant and VirtualBox using apt. 1. Install Git, Vagrant and VirtualBox using apt.
@ -103,7 +131,7 @@ machine.
$ sudo apt install git virtualbox vagrant $ sudo apt install git virtualbox vagrant
``` ```
#### Installing VirtualBox manually ##### Installing VirtualBox manually
1. Add Oracle's key to apt's list of accepted keys. 1. Add Oracle's key to apt's list of accepted keys.
@ -136,11 +164,11 @@ Example for Buster:
$ sudo apt install virtualbox-6.1 $ sudo apt install virtualbox-6.1
``` ```
### For Other GNU/Linux Distributions or *BSDs #### For Other GNU/Linux Distributions or *BSDs
1. Install Git, Vagrant and VirtualBox using your favourite package manager. 1. Install Git, Vagrant and VirtualBox using your favourite package manager.
### For macOS #### For macOS
1. Install [Homebrew](https://brew.sh/). 1. Install [Homebrew](https://brew.sh/).
@ -152,7 +180,7 @@ Example for Buster:
$ brew cask install vagrant $ brew cask install vagrant
``` ```
### For Windows #### For Windows
1. Install [Git](https://git-scm.com/download/windows), 1. Install [Git](https://git-scm.com/download/windows),
[VirtualBox](https://www.virtualbox.org/wiki/Downloads) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) and
@ -167,7 +195,7 @@ Example for Buster:
3. Run all the following commands inside Git Bash. 3. Run all the following commands inside Git Bash.
### Setting Up Development Environment Using Vagrant #### Setting Up Development Environment Using Vagrant
Vagrant is a free software command line utility for managing the life cycle of Vagrant is a free software command line utility for managing the life cycle of
virtual machines. The FreedomBox project provides ready-made virtual machines virtual machines. The FreedomBox project provides ready-made virtual machines
@ -197,7 +225,7 @@ and requires about 4.5 GB of disk space.
host$ vagrant ssh host$ vagrant ssh
``` ```
### Using the Virtual Machine #### Using the Virtual Machine
After logging into the virtual machine (VM), the source code is available in After logging into the virtual machine (VM), the source code is available in
/vagrant directory: /vagrant directory:
@ -226,7 +254,48 @@ vm$ sudo ./setup.py install
Note: This development virtual machine has automatic upgrades disabled by Note: This development virtual machine has automatic upgrades disabled by
default. default.
## Running Tests
[back to index](#hacking)
## Making/keeping FreedomBox international
### Marking text for translation
To mark text for translation, FreedomBox 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:
```python
message = _('Application successfully installed and configured.')
```
See [Django
documentation](https://docs.djangoproject.com/en/3.1/topics/i18n/translation/)
for more details.
### Translating literals (contributing translations)
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](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
[back to index](#hacking)
## Testing
### Running Tests
To run all the tests in the container/VM: To run all the tests in the container/VM:
@ -259,7 +328,7 @@ guest$ py.test-3 plinth/tests/test_actions.py::TestActions
guest$ py.test-3 plinth/tests/test_actions.py::TestActions::test_is_package_manager_busy guest$ py.test-3 plinth/tests/test_actions.py::TestActions::test_is_package_manager_busy
``` ```
## Running the Test Coverage Analysis ### Running the Test Coverage Analysis
To run the coverage tool in the container/VM: To run the coverage tool in the container/VM:
@ -281,11 +350,15 @@ 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 were executed via the tests (green) and which statements or branches were not
executed (red). executed (red).
## Running Functional Tests
### Install Dependencies [back to index](#hacking)
#### For running tests inside the container
### Functional Tests
#### Install Dependencies
##### For running tests inside the container
Inside the container run Inside the container run
@ -293,7 +366,7 @@ Inside the container run
guest$ cd /freedombox ; sudo plinth/tests/functional/install.sh guest$ cd /freedombox ; sudo plinth/tests/functional/install.sh
``` ```
#### For running tests inside the VM ##### For running tests inside the VM
From the host, provision the virtual machine with tests: From the host, provision the virtual machine with tests:
@ -301,7 +374,7 @@ From the host, provision the virtual machine with tests:
host$ vagrant provision --provision-with tests host$ vagrant provision --provision-with tests
``` ```
#### For running tests on host machine ##### For running tests on host machine
Follow the instructions below to run the tests on host machine. If you wish Follow the instructions below to run the tests on host machine. If you wish
perform the tests on host machine, the host machine must be based on Debian perform the tests on host machine, the host machine must be based on Debian
@ -321,7 +394,7 @@ host$ sudo apt install smbclient # optional, to test samba
you can place at /usr/local/bin/geckodriver . Geckodriver will use whichever you can place at /usr/local/bin/geckodriver . Geckodriver will use whichever
binary is named 'firefox' for launching the browser and interacting with it. binary is named 'firefox' for launching the browser and interacting with it.
### Run FreedomBox Service #### Run FreedomBox Service
*Warning*: Functional tests will change the configuration of the system *Warning*: Functional tests will change the configuration of the system
under test, including changing the hostname and users. Therefore you under test, including changing the hostname and users. Therefore you
@ -334,7 +407,7 @@ interface of FreedomBox should be accessible at https://localhost:4430/.
To run samba tests, port 4450 on the host should be forwarded to port 445 To run samba tests, port 4450 on the host should be forwarded to port 445
on the guest. on the guest.
### Setup FreedomBox Service for tests #### Setup FreedomBox Service for tests
Via Plinth, create a new user as follows: Via Plinth, create a new user as follows:
@ -344,7 +417,7 @@ Via Plinth, create a new user as follows:
This step is optional if a fresh install of Plinth is being tested. Functional This step is optional if a fresh install of Plinth is being tested. Functional
tests will create the required user using FreedomBox's first boot process. tests will create the required user using FreedomBox's first boot process.
### Run Functional Tests #### Running Functional Tests
**When inside a container/VM you will need to target the guest** **When inside a container/VM you will need to target the guest**
@ -380,7 +453,11 @@ installed.
$ py.test-3 -n 4 --dist=loadfile --include-functional -m essential $ py.test-3 -n 4 --dist=loadfile --include-functional -m essential
``` ```
## Building the Documentation Separately
[back to index](#hacking)
## Building the User Documentation Separately
FreedomBox Service (Plinth) man page is built from DocBook source in the `doc/` FreedomBox Service (Plinth) man page is built from DocBook source in the `doc/`
directory. FreedomBox manual is downloaded from the wiki is also available directory. FreedomBox manual is downloaded from the wiki is also available
@ -392,44 +469,21 @@ To build the documentation separately, run:
guest$ make -C doc guest$ make -C doc
``` ```
## Repository
FreedomBox Service (Plinth) is available from [back to index](#hacking)
[salsa.debian.org](https://salsa.debian.org/freedombox-team/freedombox).
## Bugs & TODO
You can report bugs on FreedomBox Service's (Plinth's) [issue ## Submitting your changes
tracker](https://salsa.debian.org/freedombox-team/freedombox/issues).
See CONTRIBUTING.md for information how to best contribute code. See [CONTRIBUTING.md](CONTRIBUTING.md) for information how to best contribute code.
## Internationalization
To mark text for translation, FreedomBox Service (Plinth) uses Django's [back to index](#hacking)
translation strings. A module should e.g. `from django.utils.translation import
ugettext as _` and wrap user-facing text with `_()`. Use it like this:
```python
message = _('Application successfully installed and configured.')
```
## Translations ## Miscelanea
The easiest way to start translating is with your browser, by using ### Application Icons
[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
## Application Icons
When adding a new App into FreedomBox, an icon is needed to represent the app in When adding a new App into FreedomBox, an icon is needed to represent the app in
the application view and for shortcuts in the front page. Follow these the application view and for shortcuts in the front page. Follow these
@ -443,3 +497,19 @@ guidelines for creating an app icon:
- Background should be transparent. - Background should be transparent.
- Leave no margins and prefer a square icon. If the icon is wide, leave top and - Leave no margins and prefer a square icon. If the icon is wide, leave top and
bottom margins. If the icon is tall, leave left and right margins. bottom margins. If the icon is tall, leave left and right margins.
### Team Coordination
The project team coordinates by means of bi-weekly [audio
calls](https://wiki.debian.org/FreedomBox/ProgressCalls) and IRC discussions on
#freedombox-dev at oftc.net.
### Other Development Informations
* Generic [contribution overview](https://wiki.debian.org/FreedomBox/Contribute)
* [How to create apps for FreedomBox (Developer Manual)](https://docs.freedombox.org)
* User Experience [design](https://wiki.debian.org/FreedomBox/Design)
* [Code contribution](https://wiki.debian.org/FreedomBox/Contribute/Code)
[back to index](#hacking)