From 65bb3fb6e073ea24e520b34755d66be187bd89be Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Sun, 27 Mar 2016 13:54:23 -0400 Subject: Hacking guide update - on polyglot Python. --- www/hacking.html.in | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) (limited to 'www') diff --git a/www/hacking.html.in b/www/hacking.html.in index 132b3104..cf0519f3 100644 --- a/www/hacking.html.in +++ b/www/hacking.html.in @@ -284,10 +284,7 @@ our long-term maintenance problem as tractable as possible.

system. Thus, the daemon and libgpsd libraries need to stay pure C. Anything that links direct to the core libraries should also be in C, because Python's alien-type facilities are still just a little too -complex and painful to be a net win for our situation. (We know this -may be about to change with the advent of the ctypes module in Python -2.6 and will keep an open mind, especially to anyone who actually -supplies a ctypes Python wrapper for libgpsd.)

+complex and painful to be a net win for our situation.

We prefer Python anywhere we aren't required to use C by technical constraints — in particular, for @@ -319,6 +316,27 @@ costs from the places in the codebase where we can least afford it to the places where it is most manageable and inflicts the least long-term maintenance burden.

+

Python version issues and good style

+ +

Because Python is not used at runtime by the daemon, Python +version-skew problem (such as the 2 to 3 transition) essentally +never have any affect on or reveal bugs in the C code.

+ +

A significant part of the reason is that in GPSD-world the notion +of "target Python" is not actually meaningful for anything but a +handful of test and profiling utilities. On the very

rare occasions +that those have had bugs (fewer than a half-dozen in the entire +project history) they have generally been due to glitches in Python's +OS bindings - the least rare categories related to the socket and pty +libraries.

+ +

Therefore, what version of Python code such as the regression-test +framework is running under is generally unimportant if it runs at all. +To minimize prroblems do to the ongoing Python 2 to 3 transition, +follow the "polyglot" guidelines in Practical +Python porting for systems programmers. +

Verify your patch or commit

GPSD is written to a high quality standard, and has a defect rate @@ -355,7 +373,7 @@ go through the following checklist:

in detail why the regression broke in your change comment.
  • After code changes that do anything to the storage handling, run - valgrind-audit and look out for reports of memory leaks and other + valgrind-audit.py and look out for reports of memory leaks and other dynamic-allocation problems (see the Valgrind website for a description of this tool if you don't already know about it).
    • @@ -379,10 +397,15 @@ following things:

    There's a whole section on adding new drivers later in this document.

    -

    Send patches in diff -u or -c format

    +

    Send patches in git-format-patch, diff -u or -c format

    + +

    Wee like getting patxges mnade using git format-patch from a +repository clone, as this means we don't have to compose a change +comment and attribution.

    -

    We prefer diff -u format, but diff -c is acceptable. Do not send -patches in the default (-e or ed) mode, as they are too brittle.

    +

    Failing that prefer diff -u format, but diff -c is acceptable. Do +not send patches in the default (-e or ed) mode, as they are too +brittle.

    When you send a patch, we expect you to do at least the first three of the same verification steps we require from -- cgit v1.2.1