From e4a50ad4638dc43749708abfd600c861346d7318 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Sat, 13 May 2023 12:35:25 -0300 Subject: [PATCH 01/15] Improve documentation and guidelines Signed-off-by: Nahuel Espinosa --- .github/ISSUE_TEMPLATE/bug_report.md | 52 ++-- .../documentation_issue_report.md | 25 +- .github/ISSUE_TEMPLATE/feature_request.md | 20 +- .github/pull_request_template.md | 39 ++- .gitignore | 8 + CONTRIBUTING.md | 251 ++++++++++-------- GETTING_STARTED.md | 63 +++++ README.md | 58 ++-- beluga/README.md | 26 ++ beluga_amcl/README.md | 62 +++++ beluga_benchmark/README.md | 9 + beluga_example/README.md | 22 ++ beluga_system_tests/README.md | 3 + 13 files changed, 401 insertions(+), 237 deletions(-) create mode 100644 .gitignore create mode 100644 GETTING_STARTED.md create mode 100644 beluga/README.md create mode 100644 beluga_amcl/README.md create mode 100644 beluga_benchmark/README.md create mode 100644 beluga_example/README.md create mode 100644 beluga_system_tests/README.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f530e4f97..c33dbf0c0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,36 +1,30 @@ --- name: Bug Report -about: Report a bug in beluga. +about: Create a report to help us improve. title: '' labels: bug --- -## Required info -- Version or commit hash: - - - -## Steps to reproduce issue - - -## Expected behavior - - -## Actual behavior - - -## Additional information - +### Bug description +_A clear and concise description of what the bug is._ + + +**Platform (please complete the following information):** + - OS: [e.g. Ubuntu Focal] + - `Beluga` version: [e.g. tag, commit sha] + +### How to reproduce +_List steps to reproduce the issue:_ +1. ... + +_Code snippets or minimal examples are always helpful, if not necessary._ + +**Expected behavior** +_A clear and concise description of what you expected to happen._ + +**Actual behavior** +_A clear and concise description of what you actually happened._ + +### Additional context +_Any other information you think could be meaningful to this issue._ diff --git a/.github/ISSUE_TEMPLATE/documentation_issue_report.md b/.github/ISSUE_TEMPLATE/documentation_issue_report.md index 1bdea068b..01b60adfc 100644 --- a/.github/ISSUE_TEMPLATE/documentation_issue_report.md +++ b/.github/ISSUE_TEMPLATE/documentation_issue_report.md @@ -1,28 +1,13 @@ --- name: Documentation Issue Report -about: Report a documentation issue, typographical error or missing content in beluga. +about: Report a documentation issue, typographical error or missing content in this project. title: '' labels: [bug, documentation] --- -## Required info -- Version or commit hash: - - +### Issue description +_A clear and concise description of what the bug is (e.g a typographical error, incorrect documentation, missing content)._ -## Description - - -## Additional information - +### Additional context +_Any other information you think could be meaningful to this issue._ diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index c9668f458..5f07afe3d 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,22 +1,16 @@ --- name: Feature Request -about: Request a new feature for beluga. +about: Suggest an idea for this project. title: '' labels: enhancement +assignees: '' --- -## Description - +### Feature description -## Definition of done - +_A clear and concise description of the feature, as well as to why it is relevant (e.g. the problem it solves, the use cases it supports, how it improves usability, etc.)_. -## Additional considerations - +### Implementation considerations + +_Any special considerations meaningful when implementing this feature._ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index de106e671..dc5113a33 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,26 +1,25 @@ - +- [ ] 🐛 Bugfix (change which fixes an issue) +- [ ] 🚀 Feature (change which adds functionality) +- [ ] 📚 Documentation (change which fixes or extends documentation) -## Summary - +### Checklist -## Checklist -- [ ] Read the [contributing guidelines](https://github.com/Ekumen-OS/beluga/blob/main/CONTRIBUTING.md). -- [ ] Configured pre-commit and ran colcon test locally. -- [ ] Signed all commits for DCO. -- [ ] Added tests (regression tests for bugs, coverage of new code for features). -- [ ] Updated documentation (as needed). -- [ ] Checked that CI is passing. +_Put an `x` in the boxes that apply. This is simply a reminder of what we will require before merging your code._ + +- [ ] Lint and unit tests (if any) pass locally with my changes +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] I have added necessary documentation (if appropriate) +- [ ] All commmits have been signed for [DCO](https://developercertificate.org/). + +### Additional comments + +_Anything worth mentioning to the reviewers._ diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..f5bf6ae98 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# Colcon build +build/ +install/ +logs/ + +# Development environments +.vscode/ +.idea/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 868958d0c..93b6d18a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,115 +1,136 @@ -# How to contribute to Beluga - -Thank you for investing your time in contributing to this project! - -## Contributions - -Any contribution that you make to this repository will -be under the Apache 2 License, as dictated by the -[license](./LICENSE): - -~~~ -5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. -~~~ - -Contributors must sign-off each commit by adding a `Signed-off-by: ...` -line to commit messages to certify that they have the right to submit -the code they are contributing to the project according to the -[Developer Certificate of Origin (DCO)](https://developercertificate.org/). - -## Getting started - -### Issues - -#### Create a new issue - -If you spot a problem or have a feature request you'd like to discuss, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). -If a related issue doesn't exist, you can [open a new issue](https://github.com/Ekumen-OS/beluga/issues/new/choose). - -### Make changes - -#### Prerequisites - -- Make sure you have [`docker compose`](https://github.com/docker/compose/tree/v2) installed ([`v2.10+`](https://github.com/docker/compose/releases/tag/v2.10.0)). - ```bash - docker compose version - ``` - If you don't, please follow [these instructions](https://docs.docker.com/compose/install/linux/). - -#### Make changes locally - -1. Clone the repository. - ```bash - git clone --recursive git@github.com:Ekumen-OS/beluga.git - ``` - -1. Build and run the development docker container. - ```bash - cd - docker/run.sh - ``` - To build the image before starting the container, use: - ```bash - docker/run.sh --build - ``` - To target an specific ROS distribution, use: - ```bash - ROSDISTRO=humble docker/run.sh - ``` - Supported distributions include `humble` and `rolling`. - -1. **[Optional]** Install pre-commit hooks. _This will probably cause you to not be able to create commits from your host machine since the hooks have dependencies that only exist in the development container._ - ```bash - cd /ws/src/beluga - pre-commit install - ``` - Alternatively, you can run the hooks manually. - ```bash - cd /ws/src/beluga - pre-commit run --all-files - ``` - -1. Create a working branch and start with your changes. The suggested branch name convention is `/`. - -1. Build and test the project. - ```bash - cd /ws - colcon build --symlink-install - colcon test - ``` - -1. Run an example application using a pre-recorded rosbag. - - ```bash - cd /ws - source install/setup.bash - ros2 launch beluga_example example_rosbag_launch.py - ``` - You also can use `teleop_twist_keyboard` to control a simulated robot. In two separate terminals run: - ```bash - cd /ws - source install/setup.bash - ros2 launch beluga_example example_launch.py - ``` - ```bash - cd /ws - source install/setup.bash - ros2 run teleop_twist_keyboard teleop_twist_keyboard - ``` - -1. Push your changes and [create a PR](https://github.com/Ekumen-OS/beluga/compare)! - -1. At the time a feature branch is squashed-and-merged into `main`, the commit message should adhere to the following good practices: - - Limit the subject line to 50 characters. - - Capitalize the subject line. - - Do not end the subject line with a period. - - Use the imperative mood in the subject line. - - Wrap the body at 72 characters. - - Use the body to explain _what_ and _why_ vs. _how_. - - See https://cbea.ms/git-commit/ for more information and the reasoning behind this. + +# Contributing to Beluga + +First off, thanks for taking the time to contribute! ❤️ + +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉 + +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: +> - Star the project +> - Tweet about it +> - Refer this project in your project's readme +> - Mention the project at local meetups and tell your friends/colleagues + + +## Table of Contents + +- [I Have a Question](#i-have-a-question) +- [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Requesting Features](#requesting-features) + - [Your First Code Contribution](#your-first-code-contribution) +- [Styleguides](#styleguides) + +## I Have a Question + +> If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/Ekumen-OS/beluga). + +Before you ask a question, it is best to search for existing [Issues](https://github.com/Ekumen-OS/beluga/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open an [Issue](https://github.com/Ekumen-OS/beluga/issues/new). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions, depending on what seems relevant. + +We will then take care of the issue as soon as possible. + +## I Want To Contribute + +> ### Legal Notice +> When contributing to this project, you must agree that you have authored 100% of the content, +> that you have the necessary rights to the content and that the content you contribute may be +> provided under the [Apache 2.0 License](./LICENSE) (item 5). + +### Reporting Bugs + + +#### Before Submitting a Bug Report + +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information, and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible versions (Make sure that you have read the [documentation](https://github.com/Ekumen-OS/beluga). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/Ekumen-OS/beluga/issues?q=label%3Abug). +- Collect information about the bug: + - Stack trace (Traceback) + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Version of the interpreter, compiler, middleware, package manager, depending on what is relevant. + - Possibly your input and the output + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? + + +#### How Do I Submit a Good Bug Report? + +We use GitHub issues to track bugs and errors. If you run into an issue with the project: + +- Open an [Issue](https://github.com/Ekumen-OS/beluga/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be labelled `needs-fix`, as well as possibly other labels, and the issue will be left to be [implemented by someone](#your-first-code-contribution). + +### Requesting Features + +This section guides you through submitting a feature request for Beluga, **including completely new additions and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. + + +#### Before Submitting a Feature Request + +- Make sure that you are using the latest version. +- Read the [documentation](https://github.com/Ekumen-OS/beluga) carefully and find out if the functionality is already covered. +- Perform a [search](https://github.com/Ekumen-OS/beluga/issues) to see if the feature has already been requested. If it has, add a comment to the existing issue instead of opening a new one. +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. + + +#### How Do I Submit a Good Feature Request? + +Feature requests are tracked as [GitHub issues](https://github.com/Ekumen-OS/beluga/issues). + +- Use a **clear and descriptive title** for the issue to identify the suggestion. +- Provide a **step-by-step description of the suggested feature** in as many details as possible. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you. +- **Explain why this feature would be useful** to most Beluga users. You may also want to point out the other projects that solved it better and which could serve as inspiration. + +### Your First Code Contribution + +This section guides you through contributing code to Beluga. Following these guidelines will help maintainers and ensure your contributions are reviewed and eventually accepted. + +#### A Primer On Project Workflow + +This projects adopts a [feature branch workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#feature-branching-git-workflow) ([forking workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow) for contributors that are not maintainers), with pull requests for code integration. Every code contribution must be associated to a [feature request](#requesting-features) or [bug report](#reporting-bugs) with enough consensus and evidence to move forward, signaled with `needs-work` and `needs-fix` labels respectively. Contributors must sign-off each commit by adding a `Signed-off-by: ...` line to every commit message to certify that they have the right to submit the code they are contributing to the project according to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). Pull requests must have reviewed and approved at least once to be merged. + +#### How Do I Submit a Good Code Contribution? + +- **Pull latest `main` branch**. Clone repository (or repository fork) locally if you haven't yet. +- **Branch from `main` branch**. Use a descriptive name for your feature branch. Make sure to prefix it with the associated issue number. +- **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. +- **Lint and test your changes**. For bug fixes, make sure regression tests are included. +- **Document your changes as needed**. For new features, make sure added functionality is clearly documented. +- **Push your feature branch**. To upstream repository (or repository fork). +- **Open pull request to `main`**. Make sure all tests and linters pass on your branch before opening. + +## Styleguides + + +### Commit messages + +Commit messages should adhere to the following good practices: + +- Limit the subject line to 50 characters. +- Capitalize the subject line. +- Do not end the subject line with a period. +- Use the imperative mood in the subject line. +- Wrap the body at 72 characters. +- Use the body to explain _what_ and _why_ vs. _how_. + +See https://cbea.ms/git-commit for more information and the reasoning behind this. + + +## Attribution +This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 000000000..fc27ff689 --- /dev/null +++ b/GETTING_STARTED.md @@ -0,0 +1,63 @@ +# Getting started with Beluga + +## Crash course + +1. **Clone the repository**. You will need `git`. + ```bash + git clone --recursive git@github.com:Ekumen-OS/beluga.git + ``` + +1. **Build and run the development docker container**. You will need [`docker-compose v2.10+`](https://github.com/docker/compose/tree/v2). + ```bash + (cd beluga && docker/run.sh) + ``` + To rebuild the image before starting the container, use: + ```bash + (cd beluga && docker/run.sh --build) + ``` + To target an specific ROS distribution, use: + ```bash + (cd beluga && ROSDISTRO=humble docker/run.sh) + ``` + Supported distributions include `humble` and `rolling`. + +1. **Build and test the project** (inside development container). + + ```bash + cd /ws + colcon build --symlink-install + colcon test + ``` + +1. **Run an example application using a ROS bag** (inside development container). + + ```bash + cd /ws + source install/setup.bash + ros2 launch beluga_example example_rosbag_launch.py + ``` + +1. **Run an example application using a simulation and teleop controls** (inside development container). + + In two separate terminals run: + ```bash + cd /ws + source install/setup.bash + ros2 launch beluga_example example_launch.py + ``` + ```bash + cd /ws + source install/setup.bash + ros2 run teleop_twist_keyboard teleop_twist_keyboard + ``` + +1. **Lint your code**. You will need [`pre-commit`](https://pre-commit.com/) and ROS dependencies (already installed in the development container). + + ```bash + cd /ws/src/beluga + pre-commit run --all-files + ``` + +## Next steps + +If you want to contribute to this project, please read the [contribuing guidelines](CONTRIBUTING.md). diff --git a/README.md b/README.md index 15a74636f..a55a09905 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,31 @@ # Beluga -![CI badge](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml/badge.svg?event=push) +[![CI pipeline](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml/badge.svg?branch=main)](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml?query=branch:main) +[![License Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) ## Overview -Beluga is an extensible library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms, -including sensor and motion models. -It also provides a _drop-in_ replacement for the `amcl` node used in [navigation2](https://github.com/ros-planning/navigation2). +Beluga is an extensible C++ library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms featuring: + +- A modular design based on orthogonal components that can be merged together using the mixin pattern. +- Good test coverage to prevent regressions and facilitate code improvements. +- Automated benchmarks that can be used to validate different configurations. https://github.com/Ekumen-OS/beluga/assets/33042669/df2a5e61-3d97-4350-b171-71bb1a09a6d0 ## Packages -| Package | Description | -|--------------------| ------------| -| `beluga` | A ROS agnostic extensible library to implement algorithms based on particle filters. | -| `beluga_amcl` | A ROS 2 wrapper, providing an executable node and a ROS 2 component.
It provides almost feature parity with `nav2_amcl`. | -| `beluga_example` | Example launch files, showing how to run beluga. | -| `beluga_benchmark` | Scripts to benchmark, profile and also compare beluga with other AMCL implementations. | - -## FAQ - -- How can I try an example? - - Check the [contributing guidelines](CONTRIBUTING.md), specifically the [_run an example application_](CONTRIBUTING.md#running_an_example) section. - -- How can I contribute to the project? - - Check the [contributing guidelines](CONTRIBUTING.md). - -- Is there API documentation? - - Yes, but it's not currently being hosted online. - You can use [a script](beluga/docs/generate_docs.sh) to generate docs for the beluga package locally. - -- Are the node parameters documented? - - You can find all the supported parameter documented in the example parameters [yaml file](beluga_example/config/params.yaml). - -- How to benchmark Beluga? - - You can find micro-benchmarks in the [test folder](beluga/test/benchmark/) of Beluga.
- For macro-benchmarking and comparing with other AMCL implementations, check the [benchmarking documentation](beluga_benchmark/docs/BENCHMARKING.md). - -- How to cpu profile Beluga? +This repository contains the following packages: - Check the [profiling documentation](beluga_benchmark/docs/PROFILING.md). +| Package | Description | +|----------------------------------------------| ------------------------------------------------------------------------------------------------------------------------| +| [`beluga`](beluga) | A ROS-agnostic extensible library to implement algorithms based on particle filters. | +| [`beluga_amcl`](beluga_amcl) | A ROS 2 wrapper, providing an executable node and a ROS 2 component.
It provides interface parity with `nav2_amcl`. | +| [`beluga_example`](beluga_example) | Example launch files, showing how to run Beluga-based nodes. | +| [`beluga_benchmark`](beluga_benchmark) | Scripts to benchmark, profile and also compare Beluga with other AMCL implementations. | +| [`beluga_system_tests`](beluga_system_tests) | System integration tests for Beluga. | -## License +## First Steps -Beluga is available under the `Apache 2.0` license. -See [LICENSE](LICENSE). +- Get hands-on experience with the [getting started](GETTING_STARTED.md) tutorial. +- Read the [contributing guidelines](CONTRIBUTING.md). diff --git a/beluga/README.md b/beluga/README.md new file mode 100644 index 000000000..4bfc79abe --- /dev/null +++ b/beluga/README.md @@ -0,0 +1,26 @@ +# Beluga + +Beluga is a ROS-agnostic C++17 library that provides implementations for Monte Carlo-based localization algorithms widely used in robotics applications. +Its modularity allows users to compose solutions from reusable modules and to combine them with new ones to configure the MCL algorithm that best suits their needs. + +## Features + +The current set of features includes: + +- A configurable particle filter with support for: + - [Structure of arrays and array of structures](https://en.wikipedia.org/wiki/AoS_and_SoA) storage policies. + - Fixed resampling and adaptive KLD resampling policies to determine how many samples to take per iteration. + - Selective resampling, on-motion resampling, interval resampling policies to determine when to resample. + - Sequential and parallel execution policies. + - Weighted mean and covariance statistics for pose estimation. +- Likelihood field and beam sensor models. +- Differential drive and omnidirectional motion models. + +## Dependencies + +Beluga is built on top of the following open source libraries: + +- [Eigen](https://gitlab.com/libeigen/eigen): A well-known C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms. +- [Sophus](https://github.com/strasdat/Sophus): A C++ implementation of Lie groups using Eigen. +- [Range](https://github.com/ericniebler/range-v3): The basis library for C++20's `std::ranges`. +- [libciabatta](https://github.com/atomgalaxy/libciabatta): A composable mixin support library. diff --git a/beluga_amcl/README.md b/beluga_amcl/README.md new file mode 100644 index 000000000..2a31db44e --- /dev/null +++ b/beluga_amcl/README.md @@ -0,0 +1,62 @@ +# Beluga AMCL + +Beluga AMCL is a ROS 2 node based on [Beluga](../beluga) featuring interface parity with +[nav2's AMCL](https://github.com/ros-planning/navigation2/tree/main/nav2_amcl). +This package can be easily integrated with code that currently uses `nav2's AMCL`. + +## ROS 2 Interface + +### Parameters + +Beluga AMCL currently supports the majority of ROS parameters used in [nav2's AMCL](https://github.com/ros-planning/navigation2/tree/main/nav2_amcl). +See the [nav2's configuration guide](https://navigation.ros.org/configuration/packages/configuring-amcl.html) and +[Beluga examples](../beluga_example/config/params.yaml) for reference. + +#### Extra Parameters + +Additionally, this node supports the following extra parameters: + +| Parameter | Description | +|--------------------------------------------------------------------|--------------------------------------------------------------------------------| +| `spatial_resolution_[x, y, theta]` | Resolution to divide the space in buckets for adaptive KLD resampling. | +| `initial_pose.covariance_[x, y, yaw, xy, xyaw, yyaw]` | Covariance to use with the initial pose when initializing the particle filter. | +| `execution_policy` | Execution policy used to process particles [seq: sequential, par: parallel]. | + +### Subscribed Topics + +The subscribed topic names can be changed with the parameters `map_topic`, `scan_topic` and `initial_pose_topic`. + +| Topic | Type | Description | +|------------------|-------------------------------------------|--------------------------------------------------------------------------| +| `map` | `nav_msgs/OccupancyGrid` | Input topic for map updates. | +| `scan` | `sensor_msgs/LaserScan` | Input topic for laser scan updates. | +| `initial_pose` | `geometry_msgs/PoseWithCovarianceStamped` | Input topic for pose and covariance to initialize the particle filter. | + +### Published Topics + +| Topic | Type | Description | +|------------------|-------------------------------------------|--------------------------------------------------------------------------| +| `particle_cloud` | `nav2_msgs/ParticleCloud` | Output topic for particle cloud published at a fixed frequency. | +| `pose` | `geometry_msgs/PoseWithCovarianceStamped` | Output topic for pose and covariance representing the filter estimation. | + +### Transforms + +The frame names can be changed with the parameters `global_frame_id`, `odom_frame_id` and `base_frame_id`. +Defaults are `map`, `odom` and `base`. + +| Transform | Description | +|-------------------|-----------------------------------------------------------------------------------------------| +| `odom` to `base` | Input transform used to update the motion model and detect movement to know when to resample. | +| `base` to `laser` | Input transform used to convert laser scan points to base frame. | +| `map` to `odom` | Output transform computed from the particle filter estimate. | + +### Exposed Services + +| Topic | Type | Description | +|------------------------------------|------------------|-------------------------------------------------------------------------------| +| `reinitialize_global_localization` | `std_srvs/Empty` | Request to reinitialize global localization without an initial pose estimate. | + +## Next Steps + +- See [example launch files](../beluga_example) showing how to run Beluga-based nodes. +- See [available benchmarks](../beluga_benchmark) for scripts and comparison with other AMCL implementations. diff --git a/beluga_benchmark/README.md b/beluga_benchmark/README.md new file mode 100644 index 000000000..b942fbccd --- /dev/null +++ b/beluga_benchmark/README.md @@ -0,0 +1,9 @@ +# Beluga Benchmark + +This package contains scripts to benchmark, profile and also compare Beluga AMCL with other implementations. + +## Getting Started + +- View [reports](docs/reports/) comparing Beluga's performance to other AMCL implementations. +- [How to benchmark Beluga?](docs/BENCHMARKING.md) +- [How to profile Beluga?](docs/PROFILING.md) diff --git a/beluga_example/README.md b/beluga_example/README.md new file mode 100644 index 000000000..311c808b5 --- /dev/null +++ b/beluga_example/README.md @@ -0,0 +1,22 @@ +# Beluga Example + +This package contains example launch files that demonstrate the use of Beluga-based nodes (e.g. [Beluga AMCL](../beluga_amcl)) with external ROS bags or simulation software. + +## Examples + +See the [getting started](../GETTING_STARTED.md) tutorial to setup a development container or install the package and dependencies from source. + +- Launch a pre-recorded ROS bag. + ```bash + ros2 launch beluga_example example_rosbag_launch.py + ``` + +- Launch a simulation that can be teleoperated. + ```bash + ros2 launch beluga_example example_launch.py + ``` + +- Launch a simulation with Beluga AMCL as a composable node. + ```bash + ros2 launch beluga_example example_component_launch.py + ``` diff --git a/beluga_system_tests/README.md b/beluga_system_tests/README.md new file mode 100644 index 000000000..e45c56b62 --- /dev/null +++ b/beluga_system_tests/README.md @@ -0,0 +1,3 @@ +# Beluga System Tests + +This package contains system integration tests for Beluga. From 96f95b6951176747f26a09384cf180df44dac79f Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Sun, 14 May 2023 16:26:43 -0300 Subject: [PATCH 02/15] Address code review comments Signed-off-by: Nahuel Espinosa Co-authored-by: Michel Hidalgo --- CONTRIBUTING.md | 2 +- README.md | 2 +- beluga/README.md | 10 +++++++--- beluga_amcl/README.md | 42 +++++++++++++++++++++++------------------- 4 files changed, 32 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 93b6d18a6..35d3679f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -103,7 +103,7 @@ This section guides you through contributing code to Beluga. Following these gui #### A Primer On Project Workflow -This projects adopts a [feature branch workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#feature-branching-git-workflow) ([forking workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow) for contributors that are not maintainers), with pull requests for code integration. Every code contribution must be associated to a [feature request](#requesting-features) or [bug report](#reporting-bugs) with enough consensus and evidence to move forward, signaled with `needs-work` and `needs-fix` labels respectively. Contributors must sign-off each commit by adding a `Signed-off-by: ...` line to every commit message to certify that they have the right to submit the code they are contributing to the project according to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). Pull requests must have reviewed and approved at least once to be merged. +This projects adopts a [feature branch workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#feature-branching-git-workflow) ([forking workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow) for contributors that are not maintainers), with pull requests for code integration. Every code contribution must be associated to a [feature request](#requesting-features) or [bug report](#reporting-bugs) with enough consensus and evidence to move forward, signaled with `needs-work` and `needs-fix` labels respectively. Contributors must sign-off each commit by adding a `Signed-off-by: ...` line to every commit message to certify that they have the right to submit the code they are contributing to the project according to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). Pull requests must have been reviewed and approved at least once to be merged. #### How Do I Submit a Good Code Contribution? diff --git a/README.md b/README.md index a55a09905..095dab697 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ This repository contains the following packages: | [`beluga`](beluga) | A ROS-agnostic extensible library to implement algorithms based on particle filters. | | [`beluga_amcl`](beluga_amcl) | A ROS 2 wrapper, providing an executable node and a ROS 2 component.
It provides interface parity with `nav2_amcl`. | | [`beluga_example`](beluga_example) | Example launch files, showing how to run Beluga-based nodes. | -| [`beluga_benchmark`](beluga_benchmark) | Scripts to benchmark, profile and also compare Beluga with other AMCL implementations. | +| [`beluga_benchmark`](beluga_benchmark) | Scripts to benchmark, profile and also compare Beluga with other MCL implementations. | | [`beluga_system_tests`](beluga_system_tests) | System integration tests for Beluga. | ## First Steps diff --git a/beluga/README.md b/beluga/README.md index 4bfc79abe..7a10fec12 100644 --- a/beluga/README.md +++ b/beluga/README.md @@ -8,9 +8,9 @@ Its modularity allows users to compose solutions from reusable modules and to co The current set of features includes: - A configurable particle filter with support for: - - [Structure of arrays and array of structures](https://en.wikipedia.org/wiki/AoS_and_SoA) storage policies. - - Fixed resampling and adaptive KLD resampling policies to determine how many samples to take per iteration. - - Selective resampling, on-motion resampling, interval resampling policies to determine when to resample. + - [Structure of arrays and array of structures][aos_soa] storage policies. + - Fixed resampling and [adaptive KLD resampling][fox2001] policies to determine how many samples to take per iteration. + - [Selective resampling][grisetti2007], on-motion resampling, interval resampling policies to determine when to resample. - Sequential and parallel execution policies. - Weighted mean and covariance statistics for pose estimation. - Likelihood field and beam sensor models. @@ -24,3 +24,7 @@ Beluga is built on top of the following open source libraries: - [Sophus](https://github.com/strasdat/Sophus): A C++ implementation of Lie groups using Eigen. - [Range](https://github.com/ericniebler/range-v3): The basis library for C++20's `std::ranges`. - [libciabatta](https://github.com/atomgalaxy/libciabatta): A composable mixin support library. + +[aos_soa]: https://en.wikipedia.org/wiki/AoS_and_SoA +[fox2001]: https://dl.acm.org/doi/10.5555/2980539.2980632 +[grisetti2007]: https://doi.org/10.1109/TRO.2006.889486 diff --git a/beluga_amcl/README.md b/beluga_amcl/README.md index 2a31db44e..e7aac5c0e 100644 --- a/beluga_amcl/README.md +++ b/beluga_amcl/README.md @@ -1,54 +1,54 @@ # Beluga AMCL Beluga AMCL is a ROS 2 node based on [Beluga](../beluga) featuring interface parity with -[nav2's AMCL](https://github.com/ros-planning/navigation2/tree/main/nav2_amcl). +[nav2's AMCL][nav2_amcl]. This package can be easily integrated with code that currently uses `nav2's AMCL`. ## ROS 2 Interface ### Parameters -Beluga AMCL currently supports the majority of ROS parameters used in [nav2's AMCL](https://github.com/ros-planning/navigation2/tree/main/nav2_amcl). -See the [nav2's configuration guide](https://navigation.ros.org/configuration/packages/configuring-amcl.html) and +Beluga AMCL currently supports the majority of ROS parameters used in [nav2's AMCL][nav2_amcl]. +See the [nav2's configuration guide][nav2_configuration_guide] and [Beluga examples](../beluga_example/config/params.yaml) for reference. #### Extra Parameters Additionally, this node supports the following extra parameters: -| Parameter | Description | -|--------------------------------------------------------------------|--------------------------------------------------------------------------------| -| `spatial_resolution_[x, y, theta]` | Resolution to divide the space in buckets for adaptive KLD resampling. | -| `initial_pose.covariance_[x, y, yaw, xy, xyaw, yyaw]` | Covariance to use with the initial pose when initializing the particle filter. | -| `execution_policy` | Execution policy used to process particles [seq: sequential, par: parallel]. | +| Parameter | Description | +|--------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| `spatial_resolution_[x, y, theta]` | Resolution for [adaptive KLD resampling][fox2001]. | +| `initial_pose.covariance_[x, y, yaw, xy, xyaw, yyaw]` | Covariance to use with the initial pose when initializing the particle filter. | +| `execution_policy` | Execution policy used to process particles [seq: sequential, par: parallel]. | ### Subscribed Topics The subscribed topic names can be changed with the parameters `map_topic`, `scan_topic` and `initial_pose_topic`. -| Topic | Type | Description | -|------------------|-------------------------------------------|--------------------------------------------------------------------------| -| `map` | `nav_msgs/OccupancyGrid` | Input topic for map updates. | -| `scan` | `sensor_msgs/LaserScan` | Input topic for laser scan updates. | -| `initial_pose` | `geometry_msgs/PoseWithCovarianceStamped` | Input topic for pose and covariance to initialize the particle filter. | +| Topic | Type | Description | +|------------------|-------------------------------------------|-----------------------------------------------------------------------------| +| `map` | `nav_msgs/OccupancyGrid` | Input topic for map updates. | +| `scan` | `sensor_msgs/LaserScan` | Input topic for laser scan updates. | +| `initial_pose` | `geometry_msgs/PoseWithCovarianceStamped` | Input topic for pose mean and covariance to initialize the particle filter. | ### Published Topics | Topic | Type | Description | |------------------|-------------------------------------------|--------------------------------------------------------------------------| | `particle_cloud` | `nav2_msgs/ParticleCloud` | Output topic for particle cloud published at a fixed frequency. | -| `pose` | `geometry_msgs/PoseWithCovarianceStamped` | Output topic for pose and covariance representing the filter estimation. | +| `pose` | `geometry_msgs/PoseWithCovarianceStamped` | Output topic for estimated pose mean and covariance in map frame. | ### Transforms The frame names can be changed with the parameters `global_frame_id`, `odom_frame_id` and `base_frame_id`. Defaults are `map`, `odom` and `base`. -| Transform | Description | -|-------------------|-----------------------------------------------------------------------------------------------| -| `odom` to `base` | Input transform used to update the motion model and detect movement to know when to resample. | -| `base` to `laser` | Input transform used to convert laser scan points to base frame. | -| `map` to `odom` | Output transform computed from the particle filter estimate. | +| Transform | Description | +|-------------------|----------------------------------------------------------------------------------------------------| +| `odom` to `base` | Input transform used by motion models and resampling policies. | +| `base` to `laser` | Input transform used to convert laser scan points to base frame. | +| `map` to `odom` | Output transform calculated from the estimated pose mean and the current _odom-to-base_ transform. | ### Exposed Services @@ -60,3 +60,7 @@ Defaults are `map`, `odom` and `base`. - See [example launch files](../beluga_example) showing how to run Beluga-based nodes. - See [available benchmarks](../beluga_benchmark) for scripts and comparison with other AMCL implementations. + +[nav2_amcl]: https://github.com/ros-planning/navigation2/tree/main/nav2_amcl +[nav2_configuration_guide]: https://navigation.ros.org/configuration/packages/configuring-amcl.html +[fox2001]: https://dl.acm.org/doi/10.5555/2980539.2980632 From ed27eafa20d476f9e72be1b120975eadeb9e7b72 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Mon, 15 May 2023 21:49:09 -0300 Subject: [PATCH 03/15] Add diagram Signed-off-by: Nahuel Espinosa Co-authored-by: Gerardo Puga --- beluga/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/beluga/README.md b/beluga/README.md index 7a10fec12..5bca592af 100644 --- a/beluga/README.md +++ b/beluga/README.md @@ -3,6 +3,8 @@ Beluga is a ROS-agnostic C++17 library that provides implementations for Monte Carlo-based localization algorithms widely used in robotics applications. Its modularity allows users to compose solutions from reusable modules and to combine them with new ones to configure the MCL algorithm that best suits their needs. +![Beluga diagram](https://github.com/Ekumen-OS/beluga/assets/33042669/c3a37ef3-e9c3-463d-99f5-7e290f96bd9f) + ## Features The current set of features includes: From 971e32d440590344d04aae1f65b0438b24b58533 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 16:38:06 -0300 Subject: [PATCH 04/15] Re-upload video Signed-off-by: Nahuel Espinosa --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 095dab697..f920b0388 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Beluga is an extensible C++ library with a ground-up implementation of the Monte - Good test coverage to prevent regressions and facilitate code improvements. - Automated benchmarks that can be used to validate different configurations. -https://github.com/Ekumen-OS/beluga/assets/33042669/df2a5e61-3d97-4350-b171-71bb1a09a6d0 +https://github.com/Ekumen-OS/beluga/assets/33042669/4481cc43-f0cd-40df-a5b4-7e0a8ccb87c6 ## Packages From 6c193e136a76775b939b27c649d879ebb2e62d70 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 16:39:10 -0300 Subject: [PATCH 05/15] Re-upload diagram Signed-off-by: Nahuel Espinosa --- beluga/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beluga/README.md b/beluga/README.md index 5bca592af..8a5304a88 100644 --- a/beluga/README.md +++ b/beluga/README.md @@ -3,7 +3,7 @@ Beluga is a ROS-agnostic C++17 library that provides implementations for Monte Carlo-based localization algorithms widely used in robotics applications. Its modularity allows users to compose solutions from reusable modules and to combine them with new ones to configure the MCL algorithm that best suits their needs. -![Beluga diagram](https://github.com/Ekumen-OS/beluga/assets/33042669/c3a37ef3-e9c3-463d-99f5-7e290f96bd9f) +![Beluga diagram](https://github.com/Ekumen-OS/beluga/assets/33042669/c3a9375c-8beb-44ee-bcde-d4c0f62f576e) ## Features From 570081679de0004a1a82d9ef2f29b2e232069b48 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 20:38:01 -0300 Subject: [PATCH 06/15] Apply suggestions from code review Co-authored-by: Gerardo Puga Signed-off-by: Nahuel Espinosa --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/ISSUE_TEMPLATE/documentation_issue_report.md | 2 +- CONTRIBUTING.md | 10 +++++----- README.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c33dbf0c0..327192b11 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -24,7 +24,7 @@ _Code snippets or minimal examples are always helpful, if not necessary._ _A clear and concise description of what you expected to happen._ **Actual behavior** -_A clear and concise description of what you actually happened._ +_A clear and concise description of what actually happened._ ### Additional context _Any other information you think could be meaningful to this issue._ diff --git a/.github/ISSUE_TEMPLATE/documentation_issue_report.md b/.github/ISSUE_TEMPLATE/documentation_issue_report.md index 01b60adfc..5c6a3df6a 100644 --- a/.github/ISSUE_TEMPLATE/documentation_issue_report.md +++ b/.github/ISSUE_TEMPLATE/documentation_issue_report.md @@ -1,6 +1,6 @@ --- name: Documentation Issue Report -about: Report a documentation issue, typographical error or missing content in this project. +about: Report a documentation issue, typographical error or missing content in this repository. title: '' labels: [bug, documentation] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35d3679f7..aec043043 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ All types of contributions are encouraged and valued. See the [Table of Contents > If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/Ekumen-OS/beluga). -Before you ask a question, it is best to search for existing [Issues](https://github.com/Ekumen-OS/beluga/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. +Before opening a new issue to ask for help, it is best to check for already existing [Issues](https://github.com/Ekumen-OS/beluga/issues) that might be relevant to your question. In case you have found a suitable issue and still need clarification, you can write your question in there. It is also advisable to search the internet for answers first. If you then still feel the need to ask a question and need clarification, we recommend the following: @@ -33,7 +33,7 @@ If you then still feel the need to ask a question and need clarification, we rec - Provide as much context as you can about what you're running into. - Provide project and platform versions, depending on what seems relevant. -We will then take care of the issue as soon as possible. +We will try to answer back as soon as possible. ## I Want To Contribute @@ -72,8 +72,8 @@ We use GitHub issues to track bugs and errors. If you run into an issue with the Once it's filed: - The project team will label the issue accordingly. -- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they are reproduced. -- If the team is able to reproduce the issue, it will be labelled `needs-fix`, as well as possibly other labels, and the issue will be left to be [implemented by someone](#your-first-code-contribution). +- A team member will try to reproduce the issue with the steps you provided. If no reproducible sequence of steps was provided or if the provided sequence does not seem to trigger the issue being reported, the team will ask you for further information about this and they will label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they've been successfully reproduced. +- If the team is able to reproduce the issue it will be labeled `needs-fix`, as well as possibly other labels, and the issue will be left to be [implemented by someone](#your-first-code-contribution). ### Requesting Features @@ -107,7 +107,7 @@ This projects adopts a [feature branch workflow](https://about.gitlab.com/topics #### How Do I Submit a Good Code Contribution? -- **Pull latest `main` branch**. Clone repository (or repository fork) locally if you haven't yet. +- **Pull the latest `main` branch**. Clone repository (or repository fork) locally if you haven't yet. - **Branch from `main` branch**. Use a descriptive name for your feature branch. Make sure to prefix it with the associated issue number. - **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. - **Lint and test your changes**. For bug fixes, make sure regression tests are included. diff --git a/README.md b/README.md index f920b0388..bac79f77f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ## Overview -Beluga is an extensible C++ library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms featuring: +Beluga is an extensible C++17 library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms featuring: - A modular design based on orthogonal components that can be merged together using the mixin pattern. - Good test coverage to prevent regressions and facilitate code improvements. From 066a6e9b2815a51e5b9929cb0e7a0b54e2a836a1 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 20:46:46 -0300 Subject: [PATCH 07/15] Reword feature request description Signed-off-by: Nahuel Espinosa --- .github/ISSUE_TEMPLATE/feature_request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 5f07afe3d..35b67b9f1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature Request -about: Suggest an idea for this project. +about: Suggest an idea for a new feature. title: '' labels: enhancement assignees: '' From d4b65fca80a38661751916e55469a05aee16816c Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 21:04:02 -0300 Subject: [PATCH 08/15] Fixed instead of implemented Signed-off-by: Nahuel Espinosa --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aec043043..43da365a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,7 @@ Once it's filed: - The project team will label the issue accordingly. - A team member will try to reproduce the issue with the steps you provided. If no reproducible sequence of steps was provided or if the provided sequence does not seem to trigger the issue being reported, the team will ask you for further information about this and they will label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they've been successfully reproduced. -- If the team is able to reproduce the issue it will be labeled `needs-fix`, as well as possibly other labels, and the issue will be left to be [implemented by someone](#your-first-code-contribution). +- If the team is able to reproduce the issue it will be labeled `needs-fix`, as well as possibly other labels, and the issue will be left to be [fixed by someone](#your-first-code-contribution). ### Requesting Features From d2d26f656dd3d429b7c8cac938e4b63129eeb646 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 21:12:33 -0300 Subject: [PATCH 09/15] Reword test coverage sentence Signed-off-by: Nahuel Espinosa --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bac79f77f..754909f7c 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Beluga is an extensible C++17 library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms featuring: - A modular design based on orthogonal components that can be merged together using the mixin pattern. -- Good test coverage to prevent regressions and facilitate code improvements. +- Emphasis on the prevention of regressions and facilitation of code improvements through test coverage. - Automated benchmarks that can be used to validate different configurations. https://github.com/Ekumen-OS/beluga/assets/33042669/4481cc43-f0cd-40df-a5b4-7e0a8ccb87c6 From f8356511b0a724c2761e248ae2fb6860c0d30e77 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 22:06:12 -0300 Subject: [PATCH 10/15] Remove sentence Signed-off-by: Nahuel Espinosa --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43da365a9..5e68d61a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ Feature requests are tracked as [GitHub issues](https://github.com/Ekumen-OS/bel - Use a **clear and descriptive title** for the issue to identify the suggestion. - Provide a **step-by-step description of the suggested feature** in as many details as possible. -- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. - **Explain why this feature would be useful** to most Beluga users. You may also want to point out the other projects that solved it better and which could serve as inspiration. ### Your First Code Contribution From 81912e0405c04e46673c40c659fa02decf26d4e4 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Tue, 16 May 2023 22:16:31 -0300 Subject: [PATCH 11/15] Reword branch instruction Signed-off-by: Nahuel Espinosa --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e68d61a2..4d80b9376 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,7 +108,7 @@ This projects adopts a [feature branch workflow](https://about.gitlab.com/topics #### How Do I Submit a Good Code Contribution? - **Pull the latest `main` branch**. Clone repository (or repository fork) locally if you haven't yet. -- **Branch from `main` branch**. Use a descriptive name for your feature branch. Make sure to prefix it with the associated issue number. +- **Create a feature branch from `main`**. Use a descriptive name and make sure to prefix it with the associated issue number. - **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. - **Lint and test your changes**. For bug fixes, make sure regression tests are included. - **Document your changes as needed**. For new features, make sure added functionality is clearly documented. From 5d1f4de22db1ad4e58d693a2758bc6d9d3ce2bd9 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Wed, 17 May 2023 11:09:01 -0300 Subject: [PATCH 12/15] Rewrite contributing instructions Signed-off-by: Nahuel Espinosa --- CONTRIBUTING.md | 22 +++++++++++++++------- GETTING_STARTED.md | 9 +++++++++ 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d80b9376..e56875ceb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,13 +107,21 @@ This projects adopts a [feature branch workflow](https://about.gitlab.com/topics #### How Do I Submit a Good Code Contribution? -- **Pull the latest `main` branch**. Clone repository (or repository fork) locally if you haven't yet. -- **Create a feature branch from `main`**. Use a descriptive name and make sure to prefix it with the associated issue number. -- **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. -- **Lint and test your changes**. For bug fixes, make sure regression tests are included. -- **Document your changes as needed**. For new features, make sure added functionality is clearly documented. -- **Push your feature branch**. To upstream repository (or repository fork). -- **Open pull request to `main`**. Make sure all tests and linters pass on your branch before opening. +1. **Fork [the Beluga repository](https://github.com/Ekumen-OS/beluga/) to your GitHub account**. +1. **Clone the repository fork locally**. + ```bash + git clone --recursive git@github.com:/beluga.git + cd beluga + ``` +1. **Create a new branch where your work will go**. + ```bash + git checkout -b /fix-issue-12345 main + ``` +1. **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. +1. **Lint and test your changes**. For bug fixes, make sure regression tests are included. +1. **Document your changes as needed**. For new features, make sure added functionality is clearly documented. +1. **Push the branch to your fork on GitHub**. +1. **Open a pull request**. Make sure all tests and linters pass on your branch before opening. ## Styleguides diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index fc27ff689..069cc5538 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -3,11 +3,13 @@ ## Crash course 1. **Clone the repository**. You will need `git`. + ```bash git clone --recursive git@github.com:Ekumen-OS/beluga.git ``` 1. **Build and run the development docker container**. You will need [`docker-compose v2.10+`](https://github.com/docker/compose/tree/v2). + ```bash (cd beluga && docker/run.sh) ``` @@ -58,6 +60,13 @@ pre-commit run --all-files ``` +1. **Build documentation** (inside development container). + + ```bash + cd /ws + ./src/beluga/docs/generate_docs.sh + ``` + ## Next steps If you want to contribute to this project, please read the [contribuing guidelines](CONTRIBUTING.md). From 04c9e52335e73a5b64a4a9b67dd12a9ff3493251 Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Wed, 17 May 2023 11:10:37 -0300 Subject: [PATCH 13/15] Reword to semi-automated Signed-off-by: Nahuel Espinosa --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 754909f7c..0916816f2 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Beluga is an extensible C++17 library with a ground-up implementation of the Mon - A modular design based on orthogonal components that can be merged together using the mixin pattern. - Emphasis on the prevention of regressions and facilitation of code improvements through test coverage. -- Automated benchmarks that can be used to validate different configurations. +- Semi-automated benchmarks that can be used to validate different configurations. https://github.com/Ekumen-OS/beluga/assets/33042669/4481cc43-f0cd-40df-a5b4-7e0a8ccb87c6 From f81d88d7bc69c546bfde1fe4b1405d015b56c95c Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Wed, 17 May 2023 11:14:08 -0300 Subject: [PATCH 14/15] Rewrite AMCL readme Signed-off-by: Nahuel Espinosa --- beluga_amcl/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/beluga_amcl/README.md b/beluga_amcl/README.md index e7aac5c0e..2bc767f1d 100644 --- a/beluga_amcl/README.md +++ b/beluga_amcl/README.md @@ -11,10 +11,7 @@ This package can be easily integrated with code that currently uses `nav2's AMCL Beluga AMCL currently supports the majority of ROS parameters used in [nav2's AMCL][nav2_amcl]. See the [nav2's configuration guide][nav2_configuration_guide] and [Beluga examples](../beluga_example/config/params.yaml) for reference. - -#### Extra Parameters - -Additionally, this node supports the following extra parameters: +In addition, it supports the following extra parameters: | Parameter | Description | |--------------------------------------------------------------------|-----------------------------------------------------------------------------------| @@ -50,7 +47,7 @@ Defaults are `map`, `odom` and `base`. | `base` to `laser` | Input transform used to convert laser scan points to base frame. | | `map` to `odom` | Output transform calculated from the estimated pose mean and the current _odom-to-base_ transform. | -### Exposed Services +### Services | Topic | Type | Description | |------------------------------------|------------------|-------------------------------------------------------------------------------| From 88b19ea3d2839666e182802f81c167cf12ef4efc Mon Sep 17 00:00:00 2001 From: Nahuel Espinosa Date: Wed, 17 May 2023 23:15:46 -0300 Subject: [PATCH 15/15] Reword and fix punctuation Signed-off-by: Nahuel Espinosa --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index dc5113a33..b38c74dda 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,7 +18,7 @@ _Put an `x` in the boxes that apply. This is simply a reminder of what we will r - [ ] Lint and unit tests (if any) pass locally with my changes - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] I have added necessary documentation (if appropriate) -- [ ] All commmits have been signed for [DCO](https://developercertificate.org/). +- [ ] All commmits have been signed for [DCO](https://developercertificate.org/) ### Additional comments diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e56875ceb..9379798d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ We use GitHub issues to track bugs and errors. If you run into an issue with the - Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. - Provide the information you collected in the previous section. -Once it's filed: +After the issue has been submitted: - The project team will label the issue accordingly. - A team member will try to reproduce the issue with the steps you provided. If no reproducible sequence of steps was provided or if the provided sequence does not seem to trigger the issue being reported, the team will ask you for further information about this and they will label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they've been successfully reproduced.