Skip to content

Latest commit

 

History

History
240 lines (187 loc) · 8.07 KB

CONTRIBUTING.md

File metadata and controls

240 lines (187 loc) · 8.07 KB

How to contribute to DGtal

In this document, we describe how to contribute to DGtal library and its DGtalTools and DGtalTools-contrib projects. Please keep in mind that DGtal is an open-source initiative under LGPL license.

A first way to contribute to the library is to give us feedbacks and comments using Github issue tracker. Do not hesitate to create an issue (feature request, bug report, issues with the documentation...).

Contribution reviewing process

We process contributions to the library using GitHub Pull-request mechanism. If you want to contribute, you would have to:

  • create an account on GitHub;
  • clone DGtal main repository (or DGtalTools, DGtalTools-contrib);
  • create a branch for your contribution and push it to your DGtal clone;
  • create a GitHub pull-request to ask for an inclusion.

Each pull-request must contain:

  • a doxygen documented source-code satisfying the coding style (see below);
  • a unit test file testing the features in the contribution (written using Catch, see for instance this tutorial);
  • a user-oriented documentation page describing the feature (using doxygen);
  • an informative pull-request comment describing the contribution;
  • a new entry in the project Changelog.md file.

Once the pull-request has been sent, a DGtal package manager will review the code and may ask for edits before being merged to the DGtal master branch. Note that we use Travis as Continuous Integration platform. When creating a pull-request, several builds are tested on several systems (linux, macos), compilers (gcc, clang) and configurations (DGtal dependencies). On Microsoft Windows platforms, we use Appeveyor service to test DGtal build. Before being merged, a pull-request must pass all these tests.

More information are described in the DGtal documentation.

Setting up Pre-commit Hooks

DGtal uses pre-commit to ensure code quality and consistency. Before making contributions, we highly recommend setting up pre-commit hooks:

Installation

  1. Install pre-commit (if not already installed):

    pip install pre-commit
  2. Install the hooks in your local repository:

    cd /path/to/DGtal
    pre-commit install

What the hooks do

The current pre-commit configuration (/.pre-commit-config.yaml) includes:

  • Removes trailing whitespace
  • Ensures files end with a newline
  • Validates YAML syntax
  • Prevents large files from being committed
  • Checks for broken symlinks
  • Detects case conflicts in filenames

Running hooks manually

By default, hooks will be run on each file ofh the commit automatically.

To run hooks on specific files:

pre-commit run --files path/to/your/files

Updating hooks

To update to the latest versions of the hooks:

pre-commit autoupdate

Skipping hooks (not recommended)

If you absolutely need to skip hooks (not recommended for regular development):

git commit --no-verify -m "Commit message"

Troubleshooting

  • If hooks fail, fix the reported issues and try committing again
  • For persistent issues, you can temporarily disable specific hooks in /.pre-commit-config.yaml
  • Ensure you're using a compatible Python version (3.6+)

Code Structure

Folders

DGtal features are organized into packages and modules (e.g. Geometry Package modules). The source code folders follows this decomposition:

  • src/DGtal/: the main source code tree.
  • Each package has its own subfolder. For instance src/DGtal/kernel for the Kernel Package.
  • Each package also contains its documentation pages (e.g. src/DGtal/kernel/doc).
  • tests/ contains all unit test files. This folder is also decomposted into package folders (e.g. tests/kernel/ for unit tests of the Kernel package modules).
  • examples/examples source files (mostly used for documentation purposes).
  • cmakecontains all cmake configuration scripts.

Namespaces

All DGtal classes and functions are contained in a DGtal:: C++ namespace. Additionally, sub-namespaces are used to gather specific codes:

  • DGtal::functions:: contains all DGtal global functions.
  • DGtal::functors:: contains all DGtal C++ functors.
  • DGtal::concepts:: contains all DGtal concepts.
  • DGtal::experimental:: contains classes and features that have a "beta" status.
  • DGtal::Z2i:: and DGtal::Z3i:: are user-oriented namespaces that contain predefined types for digital geometry in dimension 2 and 3 (respectively) using an arithmetical kernel based on DGtal::int32_t.
  • DGtal::deprecated:: contains deprecated classes and functions.
  • DGtal::detail:: contains some internal classes and functions.

Coding style

We expect the source code to match with some coding style rules described below. We strongly encourage the developers to consider scripts and unit-test/class templates provided in the DGtalScripts project. These scripts can be used to create templates of classes and tools that satisfy the guideline.

Documentation

All classes, types, methods and members must be documented using doxygen syntax. Please use DGtalScripts scripts to create package and module documentation pages.

Indent style

The DGtal indent style follow Allman Style for C/C++ code. Here you have an example:

template< typename TemplatedType>
class NewClass
{
  public:
    typedef TemplatedType Type;

    void aMethod(const int aParameter)
    {
      if ( myMember == aParameter )
      {
        something1();
        something2();
      }
      else
      {
        somethingelse1();
        somethingelse2();
      }
      finalthing();
    }

    unsigned int myMember;
};

Naming rules

  • Types/methods/variable/classes in CamelCase: (e.g. BreadthFirstVisitor, myImage...)
  • methods, functions or variables start with lowercase letter
  • Types start with capital letters ( e.g. DigitalSurface,Value...)
  • Concepts classes start with a "C" (e.g. CInteger, CSpace ...)
  • Class members are prefixed by "my" (e.g. myImage, myParameter)
  • Method or function parameter are prefixed by "a". For instance:

c++ void superFunction(const Value & aParameter);

Other rules

  • All file must contain a proper LGPL/GPL header. See the source files for examples.

  • Class member accessors/mutators

  • accessors are usually not prefixed by "get" is is name by the class member

  • if the accessor needs some computations, it is prefixed by "get"

    Value parameter() (if a Value myParameter exists)

    Value getParameter() (there is "computation")

  • Setter methods are prefixed by "set"

    anImage.setValue (...)

Contributor license agreement

At this point, we do not have Contributor License Agreement. However, contributors must agree with DGtal LGPL license and include the appropriate license header in their own code.

Documentation are published under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

If you want your package to be distributed under different licenses. Please contact us (see below).

Contacts

If you have any questions, do not hesitate to contact the developers on the mailing-lists: dgtal-devel@lists.gforge.liris.cnrs.fr or contacts@dgtal.org.