Bug#625225: python-apt-doc: minor improvements to 'Contributing to python-apt' document
Package: python-apt-doc
Version: 0.8.0~exp4
Severity: minor
Tags: patch
There was one typo, one broken link, and some inconsistency in the use of subsection underlining.
-- System Information:
Debian Release: 6.0.1
APT prefers stable-updates
APT policy: (900, 'stable-updates'), (900, 'stable')
Architecture: i386 (i686)
Kernel: Linux 2.6.38-2-686-bigmem (SMP w/2 CPU cores)
Locale: LANG=en_ZA.utf8, LC_CTYPE=en_ZA.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Versions of packages python-apt-doc depends on:
ii libjs-jquery 1.5.1-1 JavaScript library for dynamic web
ii python-apt 0.8.0~exp4 Python interface to libapt-pkg
python-apt-doc recommends no packages.
python-apt-doc suggests no packages.
-- no debconf information
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: tshepang@gmail.com-20110502153430-2nrhux7mfn1ttndz
# target_branch: http://bzr.debian.org/apt/python-apt/debian-\
# experimental/
# testament_sha1: 0f47ea31b811253a8a86bb96384b73cda58f9acb
# timestamp: 2011-05-02 17:37:24 +0200
# base_revision_id: jak@debian.org-20110429115746-do2rdff78lubdppr
#
# Begin patch
=== modified file 'doc/source/tutorials/contributing.rst'
--- doc/source/tutorials/contributing.rst 2010-05-19 13:15:36 +0000
+++ doc/source/tutorials/contributing.rst 2011-05-02 15:34:30 +0000
@@ -7,16 +7,19 @@
Let's say you need a new feature, you can develop it, and you want to get it
included in python-apt. Then be sure to follow the following guidelines.
+
Available branches
-------------------
First of all, let's talk a bit about the bzr branches of python-apt. In the
following parts, we will assume that you use bzr to create your changes and
submit them.
+
Distribution branches
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid
+
This is the official Debian branch of python-apt. All code which will be
uploaded to Debian is here. It is not as up-to-date as the mvo branch,
because this branch often gets updated just right before the release
@@ -33,6 +36,7 @@
VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-experimental/changes
**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu``
+
This is the official Ubuntu development branch. The same notes apply as
for the debian-sid branch above. For the Ubuntu release branches, replace
``ubuntu`` with the version you want; for example, for lucid:
@@ -42,8 +46,10 @@
Important Personal branches
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
+
**mvo:** lp:~mvo/python-apt/mvo
+
This is Michael Vogt's branch. Most of the development of apt happens here,
as he is the lead maintainer of python-apt.
@@ -54,7 +60,8 @@
VCS-Browser: http://bazaar.launchpad.net/~mvo/python-apt/mvo/
**jak:** http://bzr.debian.org/users/jak/python-apt/jak
- This is Julian Andres Klode's (the documentation author's) branch. This
+
+ This is Julian Andres Klode's (the documentation author) branch. This
is the place where cleanup and documentation updates happen. It is based
off debian-sid. Most stuff happens in debian-sid now.
@@ -63,8 +70,10 @@
.. highlightlang:: c
+
C++ Coding style
----------------
+
This document gives coding conventions for the C++ code comprising
the C++ extensions of Python APT. Please see the companion
informational PEP describing style guidelines for Python code (:PEP:`8`).
@@ -84,7 +93,7 @@
C++ dialect
-^^^^^^^^^^^
+-----------
- Use ISO standard C++ (the 1998 version of the standard).
@@ -95,7 +104,7 @@
Code lay-out
-^^^^^^^^^^^^
+------------
- Use 3-space indents, in files that already use them. In new source files,
that were created after this rule was introduced, use 4-space indents.
@@ -175,7 +184,7 @@
Naming conventions
-^^^^^^^^^^^^^^^^^^
+------------------
- Use a ``Py`` prefix for public functions; never for static
functions. The ``Py_`` prefix is reserved for global service
@@ -197,7 +206,8 @@
Documentation Strings
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
+
- The first line of each function docstring should be a "signature
line" that gives a brief synopsis of the arguments and return
value. For example::
@@ -228,21 +238,24 @@
Python Coding Style
-------------------
+
The coding style for all code written in python is :PEP:`8`. Exceptions from
this rule are the documentation, where code is sometimes formatted differently
to explain aspects, and functions provided for 0.7 compatibility purposes.
-When writing code, use tools like pylint, pyflakes, pychecker and pep8.py from
-http://svn.browsershots.org/trunk/devtools/pep8/ to verify that your code is
+When writing code, use tools like pylint, pyflakes, pychecker and pep8
+(all available from Debian/Ubuntu) to verify that your code is
OK. Fix all the problems which seem reasonable, and mention the unfixed issues
when asking for merge.
-In order to make the automatic generation of Python 3 code using 2to possible,
+In order to make the automatic generation of Python 3 code using 2to3 possible,
code written in Python may not utilize any functionality unsupported by 2to3 or
deprecated as of Python 2.6.
+
Submitting your patch
---------------------
+
First of all, the patch you create should be based against the most current
branch of python-apt (debian-sid or debian-experimental). If it is a bugfix,
you should probably use debian-sid. If you choose the wrong branch, we will
@@ -298,6 +311,7 @@
.. highlightlang:: sh
+
Example patch session
----------------------
In the following example, we edit a file, create a merge directive (an enhanced
# Begin bundle
IyBCYXphYXIgcmV2aXNpb24gYnVuZGxlIHY0CiMKQlpoOTFBWSZTWSB3U0kAAjB/gEDRIIBQ5///
djxGgL////BQBJ7jItjlxo7ttogShEGjRGmjKNonoIynqYRkNGjQNGgaRT9FMaaYUNRiDRgjCMEA
YABKAiZCaNCMjUh+lNqGQyMQPUDI00OYBMBMjACMTEwmEwQ0xNMBJKZU/Kh7IjUep6m1GQAAAAAH
qCMzGZ7I0GCzSzFMJUL4soFQxNqvW/+MmvBq1WzMQuh4lEE8q+aOm9vNGFo+YqsYXtMTOC0y7Q5I
9d/d7cVBBVP58hAe/wbDPbpuiZWdurlJs7XC1NZosKJRYnyxrnQJhhq3copDGLl1df2t/Wpl+/j8
KV/vvjXCT5dFbm/DVDY4VGWLpI7iDzsUi6bI0otNOu65sL9q9wyiQ2bToyfyS+lW3iBOJXISYBzi
ViYG0tVK2n/T+ZpjoRKBdNW4LXd07Ch4KiXVIU8JaFBlEWZEfn53n3uh2CoD2wRFlfPSUrRhL4Bg
8EAxYsjBHvJfP6swQuqVw73IXwt+N0CHOJ3eOUIGqPNqpKcL1/Itz2p6U3U2CS2I4KFwz8nb1S97
LMVZ8jzRpEmRJ625k0sIrM4eXCYmzMBioJXETcKljaARhGUhbyppUizQuxxGuqupsEV4IgpHDTqv
JXrLW0iW5wkNG6Rk3TUR8XsMnMHh5uVDJtOujrtquefIyEnU5aRRS6JV4V0amw2F4vWsVnRaZYio
3fHovsca3BnE1ZcwCA8ObS+ogIXGCzWoxaY02SlMbLdTuI3ukJwhVorxHQEdpbEQeqSFgux6pYUs
EFRj3uKVSUhIoDllEjGOhXM6W7dMHwMyDUx3zUU3R2VWihmpRkUqsEoSzK/VwI676LmuYx+PDcHU
iUT0qKq+TnOZD4dMHyRrYOXJxeMGJJqNhsOWO/iTR3Beiev9Bp+XzW21hJzmqAqsYSi1dakJ509m
Oa/pue/iMdPWnTIhZbjV6OxREEG2cXhfP0Cm+otiXLQlzivz5SJoTVEZpAiF1s71FFZJemmAfUMI
qmI82JbglFEjCO2G424FrDlWPFPa0O07C7lw0yXq1NAdWWpqw834UcNWXMr+e39W2dS4+TFcLYl3
YjJjKBhoKoZMITwn78YjwgjY4Ya07lO8UsTWUnnr3nHMVrjhZo3vVgMI30QxHAlNZAtVLsHgYGsX
xFXMTURBk0c+v0IWeV3ePxRY5E4cAOaScdgbMoIE54adE0pMENyraDq9Nbo0BmvgLYG8wZyyX3Bv
oik8KQdQDpNqjHRYZpFr54dd27Gp6dcyWmlJydC/ZsOonKlJPApEKf5xYdBeIn/MZwStQ/3UTWtJ
JVBUTcz+/tEZ0ojMyZmSqg3os/XtftK1S+ypnIkFriKofQzkSOwV9oNmmTIt/npz36uoHNlTbI9a
4Pv1R0w4yjenGstZUxYOo7dqXSiGN+uRUOolm3fS/ypKTwplxTCgdx8VddWFt4vw28lMvTVErSwb
qSm++eCaHTxQ4nhIVRUVWb3Dmrc/PJXcWqdesh2QzLmylkrzLESk1SNWDWIUeJ4ix7pEq+QjS0R6
jOnP67H77NEBdD1o4CNUksxrDnHXCZnpG6tRcEmq/zuJahkpZa4/8XckU4UJAgd1NJA=
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: tshepang@gmail.com-20110502153430-2nrhux7mfn1ttndz
# target_branch: http://bzr.debian.org/apt/python-apt/debian-\
# experimental/
# testament_sha1: 0f47ea31b811253a8a86bb96384b73cda58f9acb
# timestamp: 2011-05-02 17:37:24 +0200
# base_revision_id: jak@debian.org-20110429115746-do2rdff78lubdppr
#
# Begin patch
=== modified file 'doc/source/tutorials/contributing.rst'
--- doc/source/tutorials/contributing.rst 2010-05-19 13:15:36 +0000
+++ doc/source/tutorials/contributing.rst 2011-05-02 15:34:30 +0000
@@ -7,16 +7,19 @@
Let's say you need a new feature, you can develop it, and you want to get it
included in python-apt. Then be sure to follow the following guidelines.
+
Available branches
-------------------
First of all, let's talk a bit about the bzr branches of python-apt. In the
following parts, we will assume that you use bzr to create your changes and
submit them.
+
Distribution branches
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid
+
This is the official Debian branch of python-apt. All code which will be
uploaded to Debian is here. It is not as up-to-date as the mvo branch,
because this branch often gets updated just right before the release
@@ -33,6 +36,7 @@
VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-experimental/changes
**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu``
+
This is the official Ubuntu development branch. The same notes apply as
for the debian-sid branch above. For the Ubuntu release branches, replace
``ubuntu`` with the version you want; for example, for lucid:
@@ -42,8 +46,10 @@
Important Personal branches
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
+
**mvo:** lp:~mvo/python-apt/mvo
+
This is Michael Vogt's branch. Most of the development of apt happens here,
as he is the lead maintainer of python-apt.
@@ -54,7 +60,8 @@
VCS-Browser: http://bazaar.launchpad.net/~mvo/python-apt/mvo/
**jak:** http://bzr.debian.org/users/jak/python-apt/jak
- This is Julian Andres Klode's (the documentation author's) branch. This
+
+ This is Julian Andres Klode's (the documentation author) branch. This
is the place where cleanup and documentation updates happen. It is based
off debian-sid. Most stuff happens in debian-sid now.
@@ -63,8 +70,10 @@
.. highlightlang:: c
+
C++ Coding style
----------------
+
This document gives coding conventions for the C++ code comprising
the C++ extensions of Python APT. Please see the companion
informational PEP describing style guidelines for Python code (:PEP:`8`).
@@ -84,7 +93,7 @@
C++ dialect
-^^^^^^^^^^^
+-----------
- Use ISO standard C++ (the 1998 version of the standard).
@@ -95,7 +104,7 @@
Code lay-out
-^^^^^^^^^^^^
+------------
- Use 3-space indents, in files that already use them. In new source files,
that were created after this rule was introduced, use 4-space indents.
@@ -175,7 +184,7 @@
Naming conventions
-^^^^^^^^^^^^^^^^^^
+------------------
- Use a ``Py`` prefix for public functions; never for static
functions. The ``Py_`` prefix is reserved for global service
@@ -197,7 +206,8 @@
Documentation Strings
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
+
- The first line of each function docstring should be a "signature
line" that gives a brief synopsis of the arguments and return
value. For example::
@@ -228,21 +238,24 @@
Python Coding Style
-------------------
+
The coding style for all code written in python is :PEP:`8`. Exceptions from
this rule are the documentation, where code is sometimes formatted differently
to explain aspects, and functions provided for 0.7 compatibility purposes.
-When writing code, use tools like pylint, pyflakes, pychecker and pep8.py from
-http://svn.browsershots.org/trunk/devtools/pep8/ to verify that your code is
+When writing code, use tools like pylint, pyflakes, pychecker and pep8
+(all available from Debian/Ubuntu) to verify that your code is
OK. Fix all the problems which seem reasonable, and mention the unfixed issues
when asking for merge.
-In order to make the automatic generation of Python 3 code using 2to possible,
+In order to make the automatic generation of Python 3 code using 2to3 possible,
code written in Python may not utilize any functionality unsupported by 2to3 or
deprecated as of Python 2.6.
+
Submitting your patch
---------------------
+
First of all, the patch you create should be based against the most current
branch of python-apt (debian-sid or debian-experimental). If it is a bugfix,
you should probably use debian-sid. If you choose the wrong branch, we will
@@ -298,6 +311,7 @@
.. highlightlang:: sh
+
Example patch session
----------------------
In the following example, we edit a file, create a merge directive (an enhanced
# Begin bundle
IyBCYXphYXIgcmV2aXNpb24gYnVuZGxlIHY0CiMKQlpoOTFBWSZTWSB3U0kAAjB/gEDRIIBQ5///
djxGgL////BQBJ7jItjlxo7ttogShEGjRGmjKNonoIynqYRkNGjQNGgaRT9FMaaYUNRiDRgjCMEA
YABKAiZCaNCMjUh+lNqGQyMQPUDI00OYBMBMjACMTEwmEwQ0xNMBJKZU/Kh7IjUep6m1GQAAAAAH
qCMzGZ7I0GCzSzFMJUL4soFQxNqvW/+MmvBq1WzMQuh4lEE8q+aOm9vNGFo+YqsYXtMTOC0y7Q5I
9d/d7cVBBVP58hAe/wbDPbpuiZWdurlJs7XC1NZosKJRYnyxrnQJhhq3copDGLl1df2t/Wpl+/j8
KV/vvjXCT5dFbm/DVDY4VGWLpI7iDzsUi6bI0otNOu65sL9q9wyiQ2bToyfyS+lW3iBOJXISYBzi
ViYG0tVK2n/T+ZpjoRKBdNW4LXd07Ch4KiXVIU8JaFBlEWZEfn53n3uh2CoD2wRFlfPSUrRhL4Bg
8EAxYsjBHvJfP6swQuqVw73IXwt+N0CHOJ3eOUIGqPNqpKcL1/Itz2p6U3U2CS2I4KFwz8nb1S97
LMVZ8jzRpEmRJ625k0sIrM4eXCYmzMBioJXETcKljaARhGUhbyppUizQuxxGuqupsEV4IgpHDTqv
JXrLW0iW5wkNG6Rk3TUR8XsMnMHh5uVDJtOujrtquefIyEnU5aRRS6JV4V0amw2F4vWsVnRaZYio
3fHovsca3BnE1ZcwCA8ObS+ogIXGCzWoxaY02SlMbLdTuI3ukJwhVorxHQEdpbEQeqSFgux6pYUs
EFRj3uKVSUhIoDllEjGOhXM6W7dMHwMyDUx3zUU3R2VWihmpRkUqsEoSzK/VwI676LmuYx+PDcHU
iUT0qKq+TnOZD4dMHyRrYOXJxeMGJJqNhsOWO/iTR3Beiev9Bp+XzW21hJzmqAqsYSi1dakJ509m
Oa/pue/iMdPWnTIhZbjV6OxREEG2cXhfP0Cm+otiXLQlzivz5SJoTVEZpAiF1s71FFZJemmAfUMI
qmI82JbglFEjCO2G424FrDlWPFPa0O07C7lw0yXq1NAdWWpqw834UcNWXMr+e39W2dS4+TFcLYl3
YjJjKBhoKoZMITwn78YjwgjY4Ya07lO8UsTWUnnr3nHMVrjhZo3vVgMI30QxHAlNZAtVLsHgYGsX
xFXMTURBk0c+v0IWeV3ePxRY5E4cAOaScdgbMoIE54adE0pMENyraDq9Nbo0BmvgLYG8wZyyX3Bv
oik8KQdQDpNqjHRYZpFr54dd27Gp6dcyWmlJydC/ZsOonKlJPApEKf5xYdBeIn/MZwStQ/3UTWtJ
JVBUTcz+/tEZ0ojMyZmSqg3os/XtftK1S+ypnIkFriKofQzkSOwV9oNmmTIt/npz36uoHNlTbI9a
4Pv1R0w4yjenGstZUxYOo7dqXSiGN+uRUOolm3fS/ypKTwplxTCgdx8VddWFt4vw28lMvTVErSwb
qSm++eCaHTxQ4nhIVRUVWb3Dmrc/PJXcWqdesh2QzLmylkrzLESk1SNWDWIUeJ4ix7pEq+QjS0R6
jOnP67H77NEBdD1o4CNUksxrDnHXCZnpG6tRcEmq/zuJahkpZa4/8XckU4UJAgd1NJA=
Reply to: