forked from freedombox/FreedomBox
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathHACKING
141 lines (96 loc) · 5.14 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
# Hacking
## Installing for Development
1. Instead of running "setup.py install" after every source modification, run
the following command:
$ 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.
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 --no-daemon --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/*.
*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.
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.
## Running Tests
1. Run tests:
$ python3 setup.py test
## Running the Test Coverage Analysis
1. Run the coverage tool:
$ 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).
## Testing Inside a Virtual Machine
1. Checkout source on the host.
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
machine.
4. Access the guest machine's Plinth web UI from host after setting bridging or
NATing for guest virtual machine.
## Building the Documentation Separately
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:
$ make -C doc
## Repository
Plinth is available from [GitHub](https://github.com/freedombox/plinth).
## Bugs & TODO
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. You should check your code with *pep8* and *pylint* tools
before placing a merge request.
## 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:
log.error(_("Couldn't import %s: %s"), path, e)
## 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 Transifex localization platform.
https://www.transifex.com/freedombox/
https://www.debian.org/MailingLists/subscribe
For more information on translations: https://wiki.debian.org/FreedomBox/Translate