INTRODUCTION
Overview
Download and Install
Documentation
Publications

REPOSITORY
Libraries

DEVELOPER
Dev Guide
Dashboard

PEOPLE
Contributors
Users

SourceForge.net Logo
Project
Download
Mailing lists

 

         

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

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

gbx_src_life_cycle.png

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.)
 

Generated for GearBox by  doxygen 1.4.5