forked from getting-things-gnome/gtg
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
161 lines (110 loc) · 5.01 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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
=================
GTG Hacking Guide
=================
Testing
-------
You can run the unit tests for GTG with::
make check
You can also manually test your changes with debugging data with::
./gtg.sh
Using ``gtg.sh`` will prevent GTG from messing with your real data. Instead,
the debug GTG will store data in ``./tmp/default/``.
Unit tests live in ``tests/``.
Coding style
------------
In general, follow PEP 8 <http://www.python.org/dev/peps/pep-0008/>.
You should also avoid adding any 'flakes', simple Python mistakes caught by
Pyflakes <https://pypi.python.org/pypi/pyflakes>.
To check the complete cleanliness of your code, run::
$ make check
Commenting-out Code
-------------------
Try to avoid leaving commented out code in the codebase.
IT IS NOT A GOOD PRACTICE!
Or at least, if some code must be left commented out, also include a comment
or TODO or FIXME explaining why it was disabled.
Some common reasons why one might create commented code are:
a. I was unsure of my fix
b. I wasn't sure what the original code was supposed to do
c. I needed to disable it to work around some problem
d. I removed or broke other code that this code depends on
e. I started implementing something but haven't finished it yet
f. I need this for debugging problems that might still exist
Obviously none of these are great situations to be in, but it happens.
Ideally, commenting out a line of code should be a signal to yourself
that one of these things has happened, and that you probably should ask
for help before merging it to master, and it should stay in a branch for
now.
But that may not always be possible. So more practically, when
commenting out code please ALWAYS explain why you commented it out.
This enables other developers (who may know the code better) to figure
out and solve the problem.
So instead of this:
#foo.animate(x)
consider doing it like this:
#FIXME: If x is None, it causes animate() to crash. But x should
#never be None, so this *should* always work. I can't reproduce the
#crash so can't tell what makes x None. Leaving it disabled for now
#until someone can reproduce it and investigate. (LP: #12345)
#
#foo.animate(x)
Especially, avoid commented out code used for debugging. Instead of
this:
#print "Testing: ", 1, 2, 3
consider doing it like this:
Log.debug("Testing %d %d %d", 1, 2, 3)
Historically, there has been code left commented out in the codebase for
various reasons. As you run across such code, please help us tidy the
codebase by either commenting why it's disabled, or remove it.
API Style
---------
Whenever possible, prefer using task_id/tagname instead of passing task/tag
objects directly. In experimentation it's been found that passing and
using the objects directly is very expensive. Looking in a list of
objects is *much* slower than looking in a list of Strings.
If you create a method, try that that method take a task_id/tagname as
argument and return a task_id/tagname. (of course, don't apply this
blindly).
As a rule of thumb, if you put objects in a list for whatever purpose,
it should light a big warning sign ! It probably means than you have to
use the task_id/tagname instead.
The req.get_task/get_tag methods are pretty cheap (access to a
dictionary with Strings as keys) and, anyway, I discovered that a lot of
functions can already be done without the object at all if you are
consistent.
In existing tag/task object, don't hesitate to port existing functions
that does not respect that philosophy but should. (this work should take
place in gtg-refactor branch).
Copyright
---------
All modules should begin with the following header::
# -*- coding: utf-8 -*-
# -----------------------------------------------------------------------------
# Gettings Things Gnome! - a personal organizer for the GNOME desktop
# Copyright (c) 2008-2014 - Lionel Dricot & Bertrand Rousseau
#
# This program is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation, either version 3 of the License, or (at your option) any later
# version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
# details.
#
# You should have received a copy of the GNU General Public License along with
# this program. If not, see <http://www.gnu.org/licenses/>.
# -----------------------------------------------------------------------------
Submitting Patches
------------------
For information about contributing code to GTG, see
<http://gtg.readthedocs.org/en/latest/contributing.html>.
Landing Branches
----------------
1. Get the branch.
2. Run the tests, ``make check``.
3. Launch GTG with debugging data, just in case, ``./gtg.sh``.
4. Update ``CHANGELOG`` if it isn't already.
5. Update ``AUTHORS`` if the patch author is not already in there.
6. Commit your changes and propose a merge request.