[This email applies to all orocos subprojects]
I want to start a discussion about ways of improving the quality of
the "official" [*] orocos source code.
Please provide feedback on the following first draft of suggestions,
which should be regarded as complementary with respect to the
guidelines you can already find at
1/ The first basic idea is that each subproject has
- a single release manager RM (who makes final decisions)
- a limited list of people having commit-access to that subproject
(further referred to as "committers". RM is part of "committers")
2/ The second basic idea is that each "non-trivial" [**] commit should
be preceded by a review process [***].
a) Create a bug/feature report on the orocos-bugzilla
b) Submit a patch (e.g. via svn diff --diff-cmd diff -x "-u -p")
A good patch will be approved based on its
* code quality and readability (e.g. class/variable names, magic
* documentation (doxygen, xml, website [+])
* license info
* addition/modification of the necessary (unit) tests.
* subproject specific requirements (e.g. in case of BFL: add a
c) Mention on which "platforms" (RTOS-es, Matrix Libraries, Linux
Distro's) the patch was tested
d) Wait until (at least 1)(an) other committer reviews and approves
this code, or until xxx days/hours pass by
e) If you are a committer, you (or another committer) can commit
the code (atomic commits). If not, the committer who
approved the code will.
1/ In case of minor modifications ( trivial < minor < major ),
steps a) c) d) might be superfluous and posting the output of "svn
diff" on the ML might be sufficient. Again, use common sense to
determine whether a modification is minor or not.
2/ To my knowledge, this process is very similar to current
practice of the RTT and BFL subprojects.
Together with this process, I suggest to perform a cleanup operation
on the OCL subproject, in casu:
- Move all KULeuven/PMA (and other) specific code to another
* Typically the above rules are too strict for mere "application"
* There is currently so much code in OCL that people "loose the
forest between the trees". E.g. I think the usefulness of
hardware/demotool/ is very limited for the outside world.
- Review and fix the other code/documentation. Some examples I found
during a 2 minute glance at the repository (examples are randomly
* The timer component is not mentioned on the OCL overview page
* The signals subdirectory (albeit not compiled) still uses
* Lots of files (eg. hardware/ethercat-demo/EthercatIO.hpp) lack
(doxygen) documentation and licenses.
As said, this is a first draft. Feedback/Additions are welcome!
[*] Everything in orocos/trunk/bfl-kdl-ocl-rtt (and of course the
relevant tag and branch-directories)
[**] The people allowed on the committers list should have enough
"common sense" to realise whether a patch is trivial or not.
E.g. improving/adding doxygen documentation can be considered
as trivial, adapting 3 lines of example code might also be
trivial, ... Fixing a bug is probably never trivial. In case of
doubt, ask on this ML.
[***] I _do_ know this generates overhead on the short term, but I'm
convinced this will lead to time gains, more people using orocos,
... on the long term
[+] Typically not part of the patch