Merge pull request #31 from ethz-asl/feature/community_standards

Improve documentation for contributors and add a code of conduct

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

.github/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Thank you for investing time in contributing to wavemap!
+
+Please see the documentation page on [contributing](https://ethz-asl.github.io/wavemap/pages/contributing.html) to get started.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,44 @@
+---
+name: Question
+about: Ask a general question
+title: ''
+labels:
+assignees: victorreijgwart
+
+---
+
+**Question**
+A clear and concise description of your question.
+
+**Existing resources**
+Before submitting this question, please check if it has been answered in a previous [GitHub Issue](https://github.com/ethz-asl/wavemap/issues?q=is%3Aissue).
+
+If the question is about the theory behind wavemap, it might already be addressed in our [RSS paper](https://www.roboticsproceedings.org/rss19/p065.pdf).
+
+If you would like to reproduce the results from our [RSS paper](https://www.roboticsproceedings.org/rss19/p065.pdf), please refer to the [Demo](https://ethz-asl.github.io/wavemap/pages/demos.html) documentation page.
+
+If you need help configuring wavemap on a custom dataset, the [Configuration](https://ethz-asl.github.io/wavemap/pages/configuration.html) documentation page might be helpful.
+
+**Images**
+If it helps to explain your question, please include screenshots, plots or sketches.
+
+**Runtime information:**
+Please fill out these questions in case a specific dataset or sensor setup is relevant to your question.
+
+- Launch file: [e.g. Link to the launch file you used]
+- Config file: [e.g. Link to the config file you used]
+- Dataset name [e.g. Newer College Cloister sequence]  # For public datasets
+- Custom setup:                                        # For online use or personal datasets
+    - depth sensor: [e.g. Livox MID360 LiDAR]
+    - pose source: [e.g. Odometry from FastLIO2]
+
+**System information:**
+Please fill out these questions in case your hardware is relevant to your question. For example, if you would like help to tune wavemap's performance on your robot.
+
+- CPU: [e.g. Intel i9-9900K]
+- GPU: [e.g. Nvidia RTX 2080Ti]  # Only for visualization-related issues
+- RAM: [e.g. 32GB]
+- OS: [e.g. Ubuntu 20.04]
+- Wavemap
+    - install: [e.g., Native (ROS with catkin); or Docker]
+    - version: [e.g., v1.4.0]

.github/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+We currently do not expect wavemap to be exposed in security-sensitive contexts. If you intend to use wavemap in such a scenario, please contact [email protected] so that we are aware and can discuss it.
+
+We would be happy to merge security-related patches and assist with security-related improvements.

docs/pages/contributing.rst

@@ -1,17 +1,68 @@
 Contributing
 ############
 .. highlight:: bash
+.. rstcheck: ignore-roles=repo_file
 
-We are extending wavemap's API and invite you to share requests for specific interfaces by opening a `GitHub issue <https://github.com/ethz-asl/wavemap/issues>`_. Additionally, we encourage code merge requests and would be happy to review and help you optimize contributed code.
+Thank you for investing time in contributing to wavemap!
 
-To maintain code quality, we use the pre-commit framework to automatically format, lint and perform basic code checks. You can install pre-commit together with the dependencies required to run all of wavemap's checks with::
+Bug reports & Feature requests
+******************************
+We welcome bug reports, feature requests, and general questions. Please submit them through `GitHub Issues <https://github.com/ethz-asl/wavemap/issues>`_ and use the corresponding `bug report <https://github.com/ethz-asl/wavemap/issues/new?template=bug_report.md>`_, `feature request <https://github.com/ethz-asl/wavemap/issues/new?template=feature_request.md>`_, and `question <https://github.com/ethz-asl/wavemap/issues/new?template=question.md>`_ templates.
+
+In addition to requests for new functionality, do not hesitate to open feature requests for:
+
+* API methods and interfaces
+* Extensions to the documentation and examples
+
+Pull requests
+*************
+We encourage `pull requests <https://github.com/ethz-asl/wavemap/pulls>`_, especially for fixes and improvements to the documentation, code, and ROS launch and config files. Also feel free to share launch and config files for new sensor setups and applications.
+
+If you would like to contribute a new feature, please open a corresponding `feature request <https://github.com/ethz-asl/wavemap/issues/new?template=feature_request.md>`_ before you start and mention that you are willing to help with its development. This way, we can synchronize and avoid duplicated efforts.
+
+Coding standards
+****************
+This project follows the `Google Style Guide <https://google.github.io/styleguide/cppguide.html>`_ for C++.
+
+To maintain code quality, we use the `pre-commit <https://pre-commit.com/>`_ framework to automatically format, lint, and perform basic code checks. You can install pre-commit together with the dependencies required to run all of wavemap's checks with::
 
     rosrun wavemap_utils install_pre_commit.sh
 
 After running the above script, pre-commit will automatically check changed code when it is committed to git. All the checks can also be run manually at any time by calling::
 
+    # cd ~/catkin_ws/src/wavemap
     pre-commit run --all
 
+In case you really need to commit some changes that are not accepted by pre-commit, you can use git's ``--no-verify`` flag as::
+
+    git commit --no-verify -m "Your commit message"
+
+Testing
+*******
 Wavemap's codebase includes a broad suite of tests. These are run in our Continuous Integration pipeline for active merge requests, `see here <https://github.com/ethz-asl/wavemap/actions/workflows/ci.yml>`_. You can also run the tests locally with::
 
     rosrun wavemap_utils build_and_test_all.sh
+
+The tests are located in the `test` subfolders of each package and implemented using the `GoogleTest <http://google.github.io/googletest/>`_ framework.
+
+Documentation
+*************
+The documentation consists of pages for specific topics, located in the :repo_file:`docs/pages <docs/pages>` directory, and inline Doxygen annotations for the C++ source code.
+
+To read the documentation for a specific wavemap version:
+
+Latest release
+==============
+Browse to https://ethz-asl.github.io/wavemap.
+
+Specific release
+================
+Find the release in question under `GitHub Releases <https://github.com/ethz-asl/wavemap/releases>`_. Under `Assets`, at the bottom of the release's description, click and download `docs.tar`. Then unpack the archive into an empty folder and double-click index.html to open it in a browser.
+
+Local version
+=============
+In a terminal, run::
+
+    rosrun wavemap_utils preview_docs.sh
+
+This will build a preview of the documentation based on your local wavemap version and changes and open the result in a web browser.

libraries/wavemap/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 * Annotate code for profiling with Tracy Profiler

libraries/wavemap/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>Base library for wavemap.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

libraries/wavemap_io/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_io
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 * Improve error messages when reading/writing a file fails

libraries/wavemap_io/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_io</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>(De)serialization of wavemap types to files.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

ros/wavemap_msgs/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_msgs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 

ros/wavemap_msgs/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_msgs</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>Message definitions for wavemap's ROS interfaces.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

ros/wavemap_ros/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_ros
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 * Annotate code for profiling with Tracy Profiler

ros/wavemap_ros/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_ros</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>ROS interface for wavemap.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

ros/wavemap_ros_conversions/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_ros_conversions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 * Annotate code for profiling with Tracy Profiler

ros/wavemap_ros_conversions/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_ros_conversions</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>Conversions between wavemap and ROS types.</description>
 
   <maintainer email="[email protected]">Victor Reijgwart</maintainer>

ros/wavemap_rviz_plugin/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_rviz_plugin
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 

ros/wavemap_rviz_plugin/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
   <name>wavemap_rviz_plugin</name>
-  <version>1.5.0</version>
+  <version>1.5.1</version>
   <description>Plugin to interactively visualize maps published in wavemap's
     native format.
   </description>

tooling/packages/catkin_setup/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package catkin_setup
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------
 

tooling/packages/catkin_setup/package.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <package format="2">
     <name>catkin_setup</name>
-    <version>1.5.0</version>
+    <version>1.5.1</version>
     <description>Dummy package to make it easy to setup the workspace and generate the setup.[sh|bash|zsh] scripts in CI.</description>
 
     <maintainer email="[email protected]">Victor Reijgwart</maintainer>

tooling/packages/wavemap_all/CHANGELOG.rst

@@ -2,6 +2,9 @@
 Changelog for package wavemap_all
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+1.5.1 (2023-09-08)
+------------------
+
 1.5.0 (2023-09-05)
 ------------------