Skip to content

Latest commit

 

History

History
138 lines (104 loc) · 6.02 KB

contributing_instructions.md

File metadata and controls

138 lines (104 loc) · 6.02 KB
Raw

Contributing to libpointmatcher

Bug Reporting

Please use our github's issue tracker to report bugs. If you are running the library on Ubuntu, copy-paste the output of the script listVersionsUbuntu.sh to simplify the search of an answer.

Code Contributions

Libpointmatcher codebase now integrate norlab-build-system (NBS) and norlab-shell-script-tools (N2ST). NBS is a build-infrastructure-agnostic build system custom-made to meet our needs in robotic software engineering at NorLab and N2ST is a library of shell script functions as well as a shell testing tools leveraging bats-core and docker . N2ST purpose is to speed up shell script development and improve reliability.

NBS is deployed on our TeamCity continuous integration/deployment server and oversees protected branches of the libpointmatcher GitHub repository:

  • The develop branch can only be merged through a pull-request from any <feature> branches. Any contributor can submit a pull request to the develop branch;
  • the release branch is a revision and preparation branch where we can freeze the codebase in a given state without stalling to develop branch progression;
  • The master branch can only be merged through a pull-request from the release branch. Only repository admin can submit a PR to the master branch.

In any cases, submitting a pull request to develop or master will trigger a build/test configuration on our build system and the pull request will be granted if the build/test run succeed.

Current build matrix: [latest] x [x86, arm64] x [ubuntu] x [bionic, focal, jammy] x [Release, RelWithDebInfo, MinSizeRel]

Development Workflow

To speed up the development process, you can run the build system localy on your workstation and have access to stacktrace and build log. It support multi-OS and multi-architecture through docker container.

Install libpointmatcher-build-system Dependencies

cd <path/to/libpointmatcher>

# If libpointmatcher is already cloned, fetch the NBS and N2ST submodule 
git submodule update --remote --recursive --init

cd ./build_system/lpm_utility_script

# Execute docker tools install script i.e. docker daemon, docker compose, docker buildx 
bash lpm_install_docker_tools.bash

# Configure a multi-architecture docker builder
bash lpm_create_multiarch_docker_builder.bash

libpointmatcher Development › To Execute Build/Test Step Locally

cd <path/to/libpointmatcher>/build_system

# Run the build matrix as specified in ".env.build_matrix.libpointmatcher" 
#   on native architecture using "ci_PR" service 
bash lpm_crawl_libpointmatcher_build_matrix.bash --fail-fast -- build ci_PR

# Run a specific case using build flags with multi-architecture 
# virtualization using "ci_PR_amd64" and "ci_PR_arm64" services 
bash lpm_crawl_libpointmatcher_build_matrix.bash \
            --repository-version-build-matrix-override latest \
            --os-name-build-matrix-override ubuntu \
            --cmake-build-type-build-matrix-override RelWithDebInfo \
            --ubuntu-version-build-matrix-override jammy \
            --fail-fast \
            -- build ci_PR_amd64 ci_PR_arm64

# Read the help for details
bash lpm_crawl_libpointmatcher_build_matrix.bash --help

Note: To assess the state of the codebase, even for cases that are known the break the build, execute lpm_crawl_libpointmatcher_build_matrix.bleeding.bash with build matrix .env.build_matrix.libpointmatcher.bleeding. The stable build matrix used for release is .env.build_matrix.libpointmatcher.

Build System Development

cd <path/to/libpointmatcher>/build_system/tests/
 
# To execute docker dryrun and configuration tests
bash run_all_docker_dryrun_and_config_tests.bash

# To execute shell script tests
bash run_bats_core_test_in_n2st.bash

# To spin a container in interactive mode with the codebase cloned but not compiled  
cd ./tests_docker_interactive/
bash build_and_run_IamBuildSystemTester.bash bash

Build System Notes

  • lpm_crawl_dependencies_build_matrix.bash execute the build matrix for the libpointmatcher dependencies. It's not required to build them locally as they are pre-build by our TeamCity server periodically push to dockerhub. When executing lpm_crawl_libpointmatcher_build_matrix.bash, the libpointmatcher-dependencies docker images are pull and used as base image for the libpointmatcher-[ci_PR_test|release] images.
  • About libpointmatcher/.github/workflow/ vs libpointmatcher/build_system/ logic: Those are separate build logic. .github/workflow/ was community contributed and as the responsibilities of building python-binding and pushing packages. For this reason, it run a one-dimension build matrix: multiple python version, single OS version, single arch (x86) and single compile flag which GitHub action computing resources can handle just fine.

Commit Messages

This is optional for now but will eventually move our release workflow to semantic-versioning. See Commit Message References for details.

Note For Repository Admins

About Release Branch And Pull Request To Master Branch

  • Only repository admins have the privilege to push/merge on the default branch (ie: master) and the release branch.
  • Keep PR in draft mode until all the release reviewers are ready to push the release.
  • Once a PR from release -> master branch is created (not in draft mode),
    • it triggers the build-system test
    • (in-progress) and it triggers the semantic release automation

Writing Documentation

The documentation is located in the /doc folder and uses the Material for MkDocs Markdown framework.