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
|
===========================
Guidelines for contributing
===========================
Coding guidelines
=================
Like any well behaved python project out there, we are `PEP-8`_ compliant.
All the gory details are in the link, a quick way to find out whether your
code is complaint or not is via lints, such as `pylint`_ or `pep8`_.
.. _PEP-8: http://www.python.org/dev/peps/pep-0008/
.. _pylint: http://pypi.python.org/pypi/pylint
.. _pep8: http://pypi.python.org/pypi/pep8
Documentation guidelines
========================
All the documentation must be written in `rst`_. From the API documentation
to developer documentation, everything must be written in this lightweight
format.
.. _rst: http://docutils.sourceforge.net/rst.html
Project guidelines
==================
* Testing: We have strived for a good coverage in the core, and we want not
only to keep it this way, but we want even better coverage. So every
testable feature to be added to the core must be comprehensively tested.
The `twisted tool`_ that we use for testing has a `coverage`_ switch that
is very handy to back up this bold statements.
.. _twisted tool: http://twistedmatrix.com/trac/browser/trunk/twisted/trial
.. _coverage: http://twistedmatrix.com/trac/browser/trunk/twisted/scripts/trial.py#L140
* Databases: As we had some bad experiences with ORMs in the past, and our
models are not that complex, we chose to create our own ORM layer. No, we
are not suffering from NIH syndrome, it is a very simple piece of code.
Anyway all the DB related code is contained in `wader.common.provider` and
tested in `wader.test.test_provider`. The schema and all the ORM related
methods must be there. Client code should never deal with cursors,
connections, etc.
* Portability: A great deal of effort has been invested on making this
code base as portable as possible (runs on OSX and Linux). As such, you
can not add any coupling in the code to any OS. All the troublesome methods
are abstracted out via the `wader.common.oal` module. Similarly, there is
a backend system that contains all the modules required to deal with a given
environment. For example, if NetworkManager is present we will use its
profile system, while if we operate standalone, a custom one will be used.
Most of this abstractions are shown in `wader.common.interfaces`.
* Translating: No strings should be marked for translation in the core, all
the translated strings must be UI ones. The core and the UI will communicate
via exceptions that the core will raise and the UI will catch. It is here
where a localized dialog can be shown to the user.
|
