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
162
163
|
python-pcl Contribution Guide
=============================
This is a guide for all contributions to python-pcl.
The development of python-pcl is running on `the official repository at GitHub <https://github.com/strawlab/python-pcl>`_.
Anyone that wants to register an issue or to send a pull request should read through this document.
Classification of Contributions
-------------------------------
There are several ways to contribute to python-pcl community:
1. Registering an issue
2. Sending a pull request (PR)
This document mainly focuses on 1 and 2, though other contributions are also appreciated.
Release and Milestone
---------------------
We are using `GitHub Flow <http://scottchacon.com/2011/08/31/github-flow.html>`_ as our basic working process.
In particular, we are using the master branch for our development, and releases are made as tags.
Releases are classified into three groups: major, minor, and revision.
This classification is based on following criteria:
- **Major update** contains disruptive changes that break the backward compatibility.
- **Minor update** contains additions and extensions to the APIs keeping the supported backward compatibility.
- **Revision update** contains improvements on the API implementations without changing any API specification.
The release classification is reflected into the version number x.y.z, where x, y, and z corresponds to major, minor, and revision updates, respectively.
We set a milestone for an upcoming release.
The milestone is of name 'vX.Y.Z', where the version number represents a revision release at the outset.
If at least one *feature* PR is merged in the period, we rename the milestone to represent a minor release (see the next section for the PR types).
See also :doc:`compatibility`.
Issues and PRs
--------------
Issues and PRs are classified into following categories:
* **Bug**: bug reports (issues) and bug fixes (PRs)
* **Enhancement**: implementation improvements without breaking the interface
* **Feature**: feature requests (issues) and their implementations (PRs)
* **NoCompat**: disrupts backward compatibility
* **Test**: test fixes and updates
* **Document**: document fixes and improvements
* **Example**: fixes and improvements on the examples
* **Install**: fixes installation script
* **Contribution-Welcome**: issues that we request for contribution (only issues are categorized to this)
* **Other**: other issues and PRs
Issues and PRs are labeled by these categories.
This classification is often reflected into its corresponding release category: Feature issues/PRs are contained into minor/major releases and NoCompat issues/PRs are contained into major releases, while other issues/PRs can be contained into any releases including revision ones.
On registering an issue, write precise explanations on what you want python-pcl to be.
Bug reports must include necessary and sufficient conditions to reproduce the bugs.
Feature requests must include **what** you want to do (and **why** you want to do, if needed).
You can contain your thoughts on **how** to realize it into the feature requests, though **what** part is most important for discussions.
If you can write code to fix an issue, send a PR to the master branch.
Before writing your code for PRs, read through the :ref:`coding-guide`.
The description of any PR must contain a precise explanation of **what** and **how** you want to do; it is the first documentation of your code for developers, a very important part of your PR.
Once you send a PR, it is automatically tested on `Travis CI <https://travis-ci.org/strawlab/python-pcl/>`_ for Linux and Mac OS X, and on `AppVeyor <https://ci.appveyor.com/project/strawlab/python-pcl>`_ for Windows.
Your PR need to pass at least the test for Linux/MacOSX on Travis CI and Windows on AppVeyor.
After the automatic test passes, some of the core developers will start reviewing your code.
Note that this automatic PR test only includes CPU tests.
Even if your code is not complete, you can send a pull request as a *work-in-progress PR* by putting the ``[WIP]`` prefix to the PR title.
If you write a precise explanation about the PR, core developers and other contributors can join the discussion about how to proceed the PR.
.. _coding-guide:
Coding Guidelines
-----------------
We use `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ and a part of `OpenStack Style Guidelines <http://docs.openstack.org/developer/hacking/>`_ related to general coding style as our basic style guidelines.
To check your code, use ``autopep8`` and ``flake8`` command installed by ``hacking`` package::
$ pip install autopep8 hacking
$ autopep8 --global-config .pep8 path/to/your/code.py
$ flake8 path/to/your/code.py
To check Cython code, use ``.flake8.cython`` configuration file::
$ flake8 --config=.flake8.cython path/to/your/cython/code.pyx
The ``autopep8`` supports automatically correct Python code to conform to the PEP 8 style guide::
$ autopep8 --in-place --global-config .pep8 path/to/your/code.py
The ``flake8`` command lets you know the part of your code not obeying our style guidelines.
Before sending a pull request, be sure to check that your code passes the ``flake8`` checking.
Note that ``flake8`` command is not perfect.
It does not check some of the style guidelines.
Here is a (not-complete) list of the rules that ``flake8`` cannot check.
* Relative imports are prohibited. [H304]
* Importing non-module symbols is prohibited.
* Import statements must be organized into three parts: standard libraries, third-party libraries, and internal imports. [H306]
In addition, we restrict the usage of *shortcut symbols* in our code base.
They are symbols imported by packages and sub-packages of ``python-pcl``.
**It is not allowed to use such shortcuts in the ``python-pcl`` library implementation**.
Note that you can still use them in ``tests`` and ``examples`` directories.
Once you send a pull request, your coding style is automatically checked by `Travis CI <https://travis-ci.org/strawlab/python-pcl/>`_ for Linux and Mac OS X, and on `AppVeyor <https://ci.appveyor.com/project/strawlab/python-pcl>`_ for Windows.
The reviewing process starts after the check passes.
The python-pcl is designed based on PointCloudLibrary's API design. python-pcl's source code and documents contain the original PointCloudLibrary ones.
Please note the followings when writing the document.
* In order to identify overlapping parts, it is preferable to add some remarks
that this document is just copied or altered from the original one. It is
also preferable to briefly explain the specification of the function in a
short paragraph, and refer to the corresponding function in PointCloudLibrary so that
users can read the detailed document. However, it is possible to include a
complete copy of the document with such a remark if users cannot summarize
in such a way.
* If a function in python-pcl only implements a limited amount of features in the
original one, users should explicitly describe only what is implemented in
the document.
Testing Guidelines
------------------
Testing is one of the most important part of your code.
You must test your code by unit tests following our testing guidelines.
Note that we are using the nose package and the mock package for testing, so install nose and mock before writing your code::
$ pip install nose mock
In order to run unit tests at the repository root, you first have to build Cython files in place by running the following command::
$ python setup.py develop
Once the Cython modules are built, you can run unit tests simply by running ``nosetests`` command at the repository root::
$ nosetests
Tests are put into the ``tests`` directories.
Following this naming convention, you can run all the tests by just typing ``nosetests`` at the repository root::
$ nosetests
If you modify the code related to existing unit tests, you must run appropriate commands.
There are many examples of unit tests under the ``tests`` directory.
They simply use the ``unittest`` package of the standard library.
Once you send a pull request, your code is automatically tested by `Travis-CI <https://travis-ci.org/strawlab/python-pcl/>`_ and `Appveyor <https://appveyor.org/strawlab/python-pcl/>`_.
The reviewing process starts after the test passes.
.. note::
Some of numerically unstable tests might cause errors irrelevant to your changes.
In such a case, we ignore the failures and go on to the review process, so do not worry about it.
|
