Principles of Project Operation

We hope that this project will attract a diverse group of developers. If this happens we think that a clear set of written down rules would help to avoid misunderstandings.

The rules on the pages are brief. We also maintain a page with more practical instructions and a guide to common practices.

Table of contents

• 1. Tools
• 2. Project Operation
  • 2.1 Source code life cycle
    • 2.1.1 Criteria for submission
    • 2.1.2 Criteria for acceptance
    • 2.1.3 Criteria for a warning
    • 2.1.4 Criteria for disabling
    • 2.1.5 Criteria for retirement
  • 2.2 Release of source code
  • 2.3 Ownership of source code
• 3. Freedoms
• Appendix A. Programming Style Description.

1. Tools

Build system

CMake

Revision control system

Subversion

Unit test system

CTest

Documentation

Doxygen

Hosting service

SourceForge

Bug Tracking

Trac

2. Project Operation

2.1 Source code life cycle

2.1.1 Criteria for submission

Relevance

Any reusable software related to robotics. Emphasis is placed on algorithm and driver implementations. Integration frameworks are generally discouraged. Relevance of a particular library is determined through mailing list discussion.

License

Must specify an open source license.

Copyright

Must specify ownership.

2.1.2 Criteria for acceptance

Documentation

Sufficient to be useful, depends on the complexity of software, determined by peer review (at least 1 reviewer) and a public discussion on the mailing list.

Tests and sample code

Sufficient to be useful, depends on software, determined by peer review.

Programming style

Must name a known style, or describe a style (see Appendix A), and adhere to it.

Compilation

Must compile without warnings (with -Wall) on all supported platforms with all supported compilers.

Operation

Libraries must operate (within reason) as described by the documentation. Reviewers of hardware drivers are encouraged to have access to hardware where feasible.

2.1.3 Criteria for a warning

Failure of any in 2.1.2 Criteria for acceptance.

2.1.4 Criteria for disabling

Compilation

Fails to compile on any one of the supported platforms/complilers (as specified by the library developer) or does not gracefully handle one of the platforms/compilers specified as supported by Gearbox but not supported by that library - will be disabled immediatly in SVN and in any following releases until fixed

2.1.5 Criteria for retirement

Compilation

Fails for 2 months since disabling to compile on any one of the supported platforms/complilers (as specified by the library developer) or does not gracefully handle one of the platforms/compilers specified as supported by Gearbox but not supported by that library - will be moved to graveyard at the end of the 2nd month.

Other

Failure of any 2.1.2 Criteria for acceptance for 3 months after warning.

2.2 Release of source code

Regular frequent releases every 1.5-3 months.

2.3 Ownership of source code

Copyright belongs to authors and major contributors. The copyright is recorded in a comment block at the top of every source file. It is up to the current copyright holders to distinguish between "major" and "minor" contributions.

3. Freedoms

Aside from complying with Sec.2, the designer of every module within the project is not constrained in any way. We specifically mention several important freedoms:

• OS, compiler, programming language. New contributor's responsibility is to make sure that the new addition does not break the existing code.
• code design, e.g. whether or not to use C++ exceptions.
• dependencies
• data types used by libraries.

Appendix A. Programming Style Description.

In the case of not using a well-known, named style, contributors must describe the programming style in sufficient detail for others to be able to adhere to it (assuming, of course, that others are also capable of looking at the code for details). An example of what is necessary for C++ is given below.

Naming conventions

• variables, member variables, classes, structs, namespaces
• functions, member functions
• #defines, enums
• filenames
• API usage style

Units and coordinate systems

If applicable (needless to say that the units and CS's of the API must be documented separately, this applies to the code itself.)