Add pre-commit hooks & BSD 3-Clause license (#206)

* Add pre-commit hooks

* Fix unknown module issue from msgs

* Hardcode pylint version for consistency

* Add ros2-devel to workflow branches

* Remove pylint from workflow due to inconsistent errors between remote and local

* Add license

* Fix README numbering

* Fix LICENSE numbering

* Add license header to yaml files as well

.codespell-ignore

@@ -0,0 +1,2 @@
+fof
+ans

.github/LICENSE_HEADER.md

@@ -0,0 +1,2 @@
+Copyright (c) 2024, Personal Robotics Laboratory
+License: BSD 3-Clause. See LICENSE.md file in root directory.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,16 @@
 # Description
 
-[TODO: describe, in-detail, what issue this PR addresses and how it addresses it. Link to relevant Github Issues.]
+\[TODO: describe, in-detail, what issue this PR addresses and how it addresses it. Link to relevant Github Issues.\]
 
 # Testing procedure
 
-[TODO: describe, in-detail, how you tested this. The procedure must be detailed enough for the reviewer(s) to recreate it.]
+\[TODO: describe, in-detail, how you tested this. The procedure must be detailed enough for the reviewer(s) to recreate it.\]
 
 # Before opening a pull request
-- [ ] Format your code using [black formatter](https://black.readthedocs.io/en/stable/) `python3 -m black .`
-- [ ] Run your code through [pylint](https://pylint.readthedocs.io/en/latest/) and address all warnings/errors. The only warnings that are acceptable to not address is TODOs that should be addressed in a future PR. From the top-level `ada_feeding` directory, run: `pylint --recursive=y --rcfile=.pylintrc .`.
+
+- \[ \] `pre-commit run --all-files`
+- \[ \] Run your code through [pylint](https://pylint.readthedocs.io/en/latest/). `pylint --recursive=y --rcfile=.pylintrc .`. All warnings but `fixme` must be addressed.
 
 # Before Merging
-- [ ] `Squash & Merge`
+
+- \[ \] `Squash & Merge`

.github/workflows/pre-commit.yaml

@@ -0,0 +1,44 @@
+# Copyright (c) 2024, Personal Robotics Laboratory
+# License: BSD 3-Clause. See LICENSE.md file in root directory.
+
+name: pre-commit
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - ros2-devel
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: "${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: "3.10"
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      ## Run pre-commit and try to apply fixes
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+      - name: Apply fixes from pre-commit
+        uses: pre-commit-ci/lite-action@v1.0.2
+        if: always()
+      # - name: Install dependencies
+      #   run: |
+      #     python -m pip install --upgrade pip
+      #     pip install --force-reinstall pylint==3.1.0
+      #     pip install overrides
+      # - name: Analysing the code with pylint
+      #   run: |
+      #     pylint --recursive=y --rcfile=.pylintrc . --disable fixme --disable import-error

.pre-commit-config.yaml

@@ -0,0 +1,69 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-symlinks
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: destroyed-symlinks
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: requirements-txt-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.0
+    hooks:
+      - id: insert-license
+        args:
+          - --license-file
+          - .github/LICENSE_HEADER.md
+          - --use-current-year
+        types_or: [python, yaml]
+
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.0
+    hooks:
+      - id: insert-license
+        args:
+          - --license-file
+          - .github/LICENSE_HEADER.md
+          - --use-current-year
+          - --comment-style
+          - "<!--|  |-->"
+        types_or: [xml]
+        exclude: ".*package.xml$"
+
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/lovesegfault/beautysh
+    rev: v6.2.1
+    hooks:
+      - id: beautysh
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.16
+    hooks:
+      - id: mdformat
+        args:
+          - --number
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.4
+    hooks:
+      - id: codespell
+        args:
+          - --ignore-words=.codespell-ignore

.pylintrc

@@ -28,7 +28,8 @@ clear-cache-post-run=no
 extension-pkg-allow-list=cv2,
                          cv,
                          lxml,
-                         tf2_py
+                         tf2_py,
+                         rclpy._rclpy_pybind11
 
 # A comma-separated list of package or module names from where C extensions may
 # be loaded. Extensions are loading into the active Python interpreter and may
@@ -37,7 +38,8 @@ extension-pkg-allow-list=cv2,
 extension-pkg-whitelist=cv2,
                         cv,
                         lxml,
-                        tf2_py
+                        tf2_py,
+                        rclpy._rclpy_pybind11
 
 # Return non-zero exit code if any of these messages/categories are detected,
 # even if score is above --fail-under value. Syntax same as enable. Messages

LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Personal Robotics Laboratory
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -7,53 +7,71 @@ This README is the definitive source for downloading, installing, and running th
 ### Setup (Robot Software)
 
 1. [Install ROS2 Humble](https://docs.ros.org/en/humble/Installation.html) (binary packages are recommended over building from source), [configure your environment](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html), and [create a workspace](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.html#).
-    1. **NOTE**: In the remainder of the instructions, replace `~\colcon_ws` with the path to your workspace.
+
+   1. **NOTE**: In the remainder of the instructions, replace `~\colcon_ws` with the path to your workspace.
+
 2. Configure [`pr-rosinstalls`](https://github.com/personalrobotics/pr-rosinstalls) in order to download all necessary repositories.
 
-        cd ~
-        git clone https://github.com/personalrobotics/pr-rosinstalls.git
+   ```
+    cd ~
+    git clone https://github.com/personalrobotics/pr-rosinstalls.git
+   ```
 
 3. Pull all the repositories, with the correct branch. Replace `<https/ssh>` with one of the options, depending on your authentication method.
 
-        sudo apt install python3-wstool # if not already installed
-        cd ~/colcon_ws/src
-        wstool init
-        wstool merge ~/pr-rosinstalls/ada-feeding.<https/ssh>.rosinstall
-        wstool up
+   ```
+    sudo apt install python3-wstool # if not already installed
+    cd ~/colcon_ws/src
+    wstool init
+    wstool merge ~/pr-rosinstalls/ada-feeding.<https/ssh>.rosinstall
+    wstool up
+   ```
 
 4. Configure [`rosdep`](https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html):
 
-        sudo apt install python3-rosdep # if not already installed
-        sudo rosdep init # if this is the first time using rosdep
+   ```
+    sudo apt install python3-rosdep # if not already installed
+    sudo rosdep init # if this is the first time using rosdep
+   ```
 
 5. (Only for users **with** sudo access) Install [`rosdep`](https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html) dependencies:
 
-        rosdep update
-        cd ~/colcon_ws
-        rosdep install --from-paths src -y --ignore-src --as-root=pip:false
+   ```
+    rosdep update
+    cd ~/colcon_ws
+    rosdep install --from-paths src -y --ignore-src --as-root=pip:false
+   ```
 
 6. Install and fix pip/non-`rosdep` dependencies:
 
-        cd ~/colcon_ws/src/ada_feeding
-        python3 -m pip install -r requirements.txt
-
-    - Upgrade `transforms3d`, since [the release on Ubuntu packages is outdated](https://github.com/matthew-brett/transforms3d/issues/65): `python3 -m pip install transforms3d -U`
-    - Remove the duplicate matplotlib pip installation caused by installing scikit-spatial with pip (some accounts have required sudo access for this command, other have not. If you do not have sudo access and encounter this, contact a lab member who does):
-
-      ```
-        python3 -m pip uninstall matplotlib
-      ```
-      
-    - [`pyrealsense2` is not released for ARM systems](https://github.com/IntelRealSense/librealsense/issues/6449#issuecomment-650784066), so ARM users will have to [build from source](https://github.com/IntelRealSense/librealsense/blob/master/wrappers/python/readme.md#building-from-source). You may have to add the `-DPYTHON_EXECUTABLE=/usr/bin/python3` flag to the `cmake` command. When running `sudo make install`, pay close attention to which path `pyrealsense2` is installed to and add *that path* to the `PYTHONPATH` -- it should be `/use/local/lib` but may be `/usr/local/OFF`.
-   
+   ```
+    cd ~/colcon_ws/src/ada_feeding
+    python3 -m pip install -r requirements.txt
+   ```
+
+   - Upgrade `transforms3d`, since [the release on Ubuntu packages is outdated](https://github.com/matthew-brett/transforms3d/issues/65): `python3 -m pip install transforms3d -U`
+
+   - Remove the duplicate matplotlib pip installation caused by installing scikit-spatial with pip (some accounts have required sudo access for this command, other have not. If you do not have sudo access and encounter this, contact a lab member who does):
+
+     ```
+       python3 -m pip uninstall matplotlib
+     ```
+
+   - [`pyrealsense2` is not released for ARM systems](https://github.com/IntelRealSense/librealsense/issues/6449#issuecomment-650784066), so ARM users will have to [build from source](https://github.com/IntelRealSense/librealsense/blob/master/wrappers/python/readme.md#building-from-source). You may have to add the `-DPYTHON_EXECUTABLE=/usr/bin/python3` flag to the `cmake` command. When running `sudo make install`, pay close attention to which path `pyrealsense2` is installed to and add *that path* to the `PYTHONPATH` -- it should be `/use/local/lib` but may be `/usr/local/OFF`.
+
 7. Install the JACO SDK (real robot only). All SDKs are listed [here](https://www.kinovarobotics.com/resources?r=79301&s); PRL currently uses the [Gen2 SDK v1.5.1](https://drive.google.com/file/d/1UEQAow0XLcVcPCeQfHK9ERBihOCclkJ9/view). Note that although the latest version of that SDK is for Ubuntu 16.04, it still works on Ubuntu 22.04 (only for x86 systems, not ARM system).
+
 8. (Optional): We recommend using CycloneDDS as your ROS2 midleware, with a custom configuration file that enables multicast on loopback and prioritizes loopback. Install it with `sudo apt install ros-humble-rmw-cyclonedds-cpp`. Then, add the following lines to your `~/bashrc`: `export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp; export CYCLONEDDS_URI=~/colcon_ws/src/ada_feeding/cyclonedds.xml`.
-    - Note that you may have to change the name of the fallback interface that CycloneDDS uses if `lo` does not work for that transmission. To do so, run `ifconfig` and either use the name of your ethernet network or WiFi network, depending on how your computer is connected to the internet.
-    - Note that you have to [rebuild your workspace from scratch after doing this](https://docs.ros.org/en/humble/How-To-Guides/Working-with-multiple-RMW-implementations.html#adding-rmw-implementations-to-your-workspace).
+
+   - Note that you may have to change the name of the fallback interface that CycloneDDS uses if `lo` does not work for that transmission. To do so, run `ifconfig` and either use the name of your ethernet network or WiFi network, depending on how your computer is connected to the internet.
+   - Note that you have to [rebuild your workspace from scratch after doing this](https://docs.ros.org/en/humble/How-To-Guides/Working-with-multiple-RMW-implementations.html#adding-rmw-implementations-to-your-workspace).
+
 9. Build your workspace:
 
-        cd ~/colcon_ws
-        colcon build --symlink-install # if sim-only, add '--packages-skip ada_hardware'
+   ```
+    cd ~/colcon_ws
+    colcon build --symlink-install # if sim-only, add '--packages-skip ada_hardware'
+   ```
 
 ### Setup (System Configuration)
 
@@ -68,31 +86,39 @@ If you change the e-stop button, the e-stop button's adapter(s), and/or the devi
 ### Setup (Web App)
 
 1. Install the Node Version Manager (nvm): https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script
+
 2. Install and use NodeJS 21 (Note: if you have just installed nvm using the previous command, you will need to source your .bashrc or open a new terminal to run these commands):
 
-        nvm install 21
-        nvm use 21
+   ```
+    nvm install 21
+    nvm use 21
+   ```
 
 3. (Only for users **with** sudo access; this should already be configured on PRL computers) Make Node available to all users, including root:
 
-        sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/node" "/usr/local/bin/node"
-        sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/npm" "/usr/local/bin/npm"
-        sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/npx" "/usr/local/bin/npx"
+   ```
+    sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/node" "/usr/local/bin/node"
+    sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/npm" "/usr/local/bin/npm"
+    sudo ln -s "$NVM_DIR/versions/node/$(nvm version)/bin/npx" "/usr/local/bin/npx"
+   ```
 
 4. (Only for users **with** sudo access; this should already be configured on PRL computers) Install `serve` and `pm2` globally. Root access is necessary for `serve` so it can access port 80.
 
-        sudo npm install -g serve
-        npm install -g pm2@latest
+   ```
+    sudo npm install -g serve
+    npm install -g pm2@latest
+   ```
 
 5. Install the web app dependencies. (Note: there will be some vulnerabilities in dependencies. This is okay, since access to the web app is shielded behind our secure router.)
 
-        cd ~/colcon_ws/src/feeding_web_interface/feedingwebapp
-        npm install --legacy-peer-deps
-        npx playwright install
+   ```
+    cd ~/colcon_ws/src/feeding_web_interface/feedingwebapp
+    npm install --legacy-peer-deps
+    npx playwright install
+   ```
 
 6. (Optional; this should already be configured on PRL computers) To access the web app on a device other than the one hosting it, enable the desired port for HTTP access: https://www.digitalocean.com/community/tutorials/ufw-essentials-common-firewall-rules-and-commands#allow-all-incoming-http-port-80
 
-
 ## Running the Software
 
 We use the convenience script `start.py` to launch the software. This script has several command-line arguments, which can be seen by passing the `-h` flag when running the script.
@@ -112,7 +138,6 @@ In a browser, access `127.0.0.1` (if on the same device serving the web app), or
 
 To close, run `python3 src/ada_feeding/start.py -c`
 
-
 ### Option B: Running Web App With the Mock Robot
 
 This option starts the web app, runs dummy nodes for perception, runs the **real** robot motion code, but runs a mock robot in MoveIt. This is useful for testing robot motion code in simulation before moving onto the real robot. This will start the web app on port `3000` and does not require `sudo` access.
@@ -143,7 +168,6 @@ To close, run `python3 src/ada_feeding/start.py --sim dummy -c`
 
 - **Something is not working, what do I do?**: All our code runs in `screen` sessions, so the first step is to attach to individual screen sessions to identify where the issue is. Run `screen -ls` to list all screens, run `screen -r <name>` to attach to a screen session, and `Ctrl-A d` to detach from the screen session. An introduction to `screen` can be found [here](https://astrobiomike.github.io/unix/screen-intro).
 - **The watchdog is not recognizing my initial e-stop click**: Verify the e-stop is plugged in, and that any other processes accessing the microphone (e.g., Sound Settings) are closed. Run `alsamixer` to see if your user account has access to it. If you do not see sound levels in the terminal, try `sudo alsamixer`. If that works, give your user account permission to access sound: `sudo setfacl -m u:$USER:rw /dev/snd/*`
-- **The watchdog is failing due to the F/T sensor**: First, check whether the force-torque sensor is publishing: `ros2 topic echo /wireless_ft/ftSensor3`. If not, the issue is in the `ft` screen (one potential issue is that the alias `ft-sensor` does not point to the right IP address for the force-torque sensor, in which case you should pass the IP address in using the `host` parameter). If so, check the timestamp of the published F/T messages compared to the current time. If it is off, the problem is that NTP got disabled on the force-torque sensor. You have to use `minicom` to re-enable NTP (see [here](https://github.com/personalrobotics/pr_docs/wiki/ADA) for PRL-specific instructions). 
+- **The watchdog is failing due to the F/T sensor**: First, check whether the force-torque sensor is publishing: `ros2 topic echo /wireless_ft/ftSensor3`. If not, the issue is in the `ft` screen (one potential issue is that the alias `ft-sensor` does not point to the right IP address for the force-torque sensor, in which case you should pass the IP address in using the `host` parameter). If so, check the timestamp of the published F/T messages compared to the current time. If it is off, the problem is that NTP got disabled on the force-torque sensor. You have to use `minicom` to re-enable NTP (see [here](https://github.com/personalrobotics/pr_docs/wiki/ADA) for PRL-specific instructions).
 - **I get the error `cannot use destroyable because destruction was requested`**: Upgrade to the latest version of`rclpy`.
-- **I get the error `rosbags is not installed, or a wrong version is installed (needs 0.9.19). Type Checking against rosbag types will not work. Error: No module named 'rosbags'`**: Upgrade or downgrade to `rosbags` version 0.9.19.
 - **I get the error `bad option: --env-file=.env` when launching the WebRTC Signalling Server**: You are using an old version of Node; upgrade it to 21.