Contribution Rules and Coding Standards

  • NB: Last update 23.Jun.2016

Important: before submitting a contribution

OpenViBE is free to use and the source code is freely available. However, there are requirements concerning code and patch submissions to the software. Please note the following:

  • contrib/ folder: Contributions can be freely submitted to the contrib/ folder of the OpenViBE distribution. The authors retain the rights to their work. The contribution must have an AGPL3 compatible license and preferably follow the OpenViBE coding standards. Contributions such as drivers and boxes can be accepted in this category.
  • All other folders: Contributing to any other folder than contrib/, the contributor must transfer the rights of the work to Inria (details). The work must follow the OpenViBE coding standards. For example, kernel and application modifications belong to this class.

In both cases, the contributor will be considered the moral author of the contributed work, and be acknowledged for in it in the release notes, web documentation, and other places that may apply (such as source code, for contributed modules).

Practical significance between contrib/ and the rest. Some components such as boxes and Acquisition Server drivers can reside either in contrib/ or the non-contrib parts of the source tree. In such a case, it is worth considering which perimeter the contribution should preferably be in. The difference between the two is that if Inria is granted the copyright transfer, it can dual-license the contribution to be contained in third-party products derived from OpenViBE. At the moment these are for example the NeuroRT Studio and ADHD treatment solutions from Mensia Technologies. Materials in contrib/ cannot be used in that way in derived products. Hence, contributors such as manufacturers that are interested in getting maximal user coverage might consider transferring the copyright for that reason.

Note that all contributions are individually considered for inclusion by the OpenViBE dev team and may be rejected. Especially high standards are required for any contributions to the OpenViBE kernel core. If you have any questions about making a contribution, please do not hesitate to contact the lead engineer directly.


Copyright transfer details

If your contribution is not targeted to the contrib/ folder, a copyright transfer is required in order for your contribution to be considered for inclusion in the OpenViBE source tree. In that case, you need to transfer the rights of the work to Inria (France). This is done by signing a copyright transfer agreement. The form used will depend on your circumstances:

  • If you work for another: If the ownership of your work actually belongs to your employer according to your work contract, you must ask us an institutional contributor form. The form must be signed by a representative of your company who is authorized to do so.
  • If you’re independent / freelance: If the rights of your work belong to you, please ask us for an individual contributor form. In this case you can sign the form yourself.

Due to the French law, the signed agreement must be mailed via post in two physical copies. One copy will be sent back to you with Inria’s signature. If you intend to transfer a copyright, please contact us directly letting us know which form would you need and a brief description of what you intend to contribute.


Concerning driver contributions

There are a few simple notes to make regarding our practices for driver contributions.

  • The contributor should take care that the driver works as intended, with some acceptable level of quality. Without access to the hardware, the OpenViBE developers cannot really test the driver. What we can do is to keep the driver compiling and linking from one OpenViBE version to another, and bundle it with the releases.
  • The driver may depend on proprietary materials either compile time or run-time. If we should not redistribute either of these materials with OpenViBE, you must clearly indicate so with the necessary details.
  • The OpenViBE engineers will require the needed compile-time materials for the intended platforms (libraries, APIs, etc) if any, in order to compile and link the driver.
  • On Windows, any library dependencies should be 32bit. If they have been implemented with Visual Studio, we’d prefer the 2013 version (in order to minimize the number of redist packages required by OpenViBE).
  • In the case the driver relies on proprietary materials run-time, the users who do not have them must still be able to use the Acquisition Server normally. If the user selects your driver in that case, the driver should gracefully print an error message about the missing materials and return ‘false’ from the driver code handling the ‘Connect’ and/or ‘Driver Properties’ buttons.
  • On the Supported Hardware -page, we can mention the contributor as the party to contact regarding questions to the driver. Alternatively, we can omit this information. You can let us know which you prefer. The OpenViBE core developers do not know the device or the driver well enough to answer questions specific to it.

If you have further questions about driver contributions, feel free to contact us.


OpenViBE coding standards

Developers wishing to contribute to OpenViBE should be aware that several coding rules have been fixed to ensure homogeneous source code. These rules are as follows :

  • namings :
    • English is used for all names (class, function, variable…)
    • Abreviations are not tolerated anywhere in the code. All names must be as explicit as possible (makes it a bit longer to write code when automatic completion is not available, but in turn it is much easier to read for people who did not write this code!)
    • class names start with C
    • template names start with T
    • interface names start with I (as with pure abstract classes of an API)
    • members start with m_
    • local variables start with l_
    • global variables are prohibited (please contact the dev coordinator if this is necessary in your case)
    • function parameter names do not have a specific prefix
    • variable names are prefixed with their type : b for boolean, s for string, r for references, o for objects, i16 for signed 16 bits integers, ui64 for unsigned 64 bits integers or f64 for 64 bits floats…
    • function names do not have a prefix, start with a lowercase character and use upper case characters for each new word (no underscore)
    • curly brackets always stand alone on new lines
    • if / else blocks always have curly brackets, even if only one call is to be done
  • English is used in all code documentation
  • All files must be encoded in ASCII
  • No special characters, even in the comment blocks
  • Code documentation is done with doxygen (http://www.stack.nl/~dimitri/doxygen/)
  • Implementation is documented for complex things with or without doxygen
  • non portable libraries (should it be software or hardware compatibility) are isolated in separate modules (such as EBML, XML, FS etc…)
  • every class is constituted by a pair of files : header (definition) and source (implementation)
  • redundant includes should be avoided thanks to ifndef define endif directives at the beginning and end of header files
  • if your component depends on third-party headers, use include guards to disable the compilation of the module if all dependencies are not available.
  • API header files should be stored in a folder named after the module name
  • At least one namespace should be used per module so to avoid symbol name collisions
  • ‘using namespace’ directives must not be used in header files
  • generalized use of basic types provided by modules (float32, uint32 and so on) is strongly encouraged so that type sizes are explicit throughout the code and thus at any time, a developer knows what can be done with the values being manipulated.
  • Indentation :
    • At the beginning of each code line, use tab to indent. In OpenViBE code, 1 tab must equal 4 spaces.
    • In the middle of each code line (i.e. after some text), use spaces to align the rest (e.g. trailing comments).
  • Boxes, scenarios or drivers should not create new files to the current directory or to the install tree, as this may mean writing to “Program Files/” or “/usr/” – bad. Instead, files should be generated under ${Player_ScenarioDirectory} or ${Path_UserData}.
  • Printing should be done using the LogManager. Do not use printf() or cout if you can avoid them.

This is a sample of OpenViBE-compliant code illustrating these rules :

/*
 * \file SampleFile.h
 * \author me
 * \date today
 * \brief a sample file containing TSample template
 *
 * This sample file contains the definition of the
 * TSample template blah blah more details...
 */
namespace SampleNamespace
{ 
    /**
     * \class Tsample
     * \author me
     * \date today
     * \brief short-blah
     *
     * Detailed blah blah
     */
    template class TSample : public T
    {
    public:
		/**
		* \function sampleFunction
		* \param rInputValue[in] : blah
		* \param rOutputValue[out] : blah
		* \return blah blah
		* \brief short-blah
		*
		* Detailed blah blah
		*/
		virtual SampleNamespace::boolean sampleFunction(
			SampleNamespace::boolean bInputValue,
			SampleNamespace::boolean& rOutputValue)
		{
			SampleNamespace::boolean l_bCondition=true;
			if(l_bCondition)
			{
				rOutputValue=bInputValue;   // This comment is indented with space
				return true;                // This too...
			}
			return false;
		}
	};
};

Access levels

Integrating contributions is done on different levels.

  • First, senior developers of the core team have full access to the repository. They can modify any file.
  • Next, junior developers of the core team have access to work on their own branches in the repository. Integration to the master branch is decided with the senior developers.
  • Finally, community contributors typically have a read-only access to the repository. Contributors may produce patches and develop custom functionalities locally, and email them to the core team as candidates for inclusion. Creating such patches may be done easily by dumping the output of a git diff.
This entry was posted in Architecture and practices and tagged . Bookmark the permalink.