Devel

.devcontainer/devcontainer.json

@@ -0,0 +1,5 @@
+{
+  "name": "CDE for robots-configuration",
+  "image": "ghcr.io/robotology/robots-configuration:latest",
+  "remoteUser": "codespace"
+}

.githooks/post-commit

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Retrieve the value of the environment variable
+ENV_VAR_VALUE=$(printenv YARP_ROBOT_NAME)
+
+echo "Post-commit hook running..."
+
+# Check if the environment variable is set
+if [ -z "$ENV_VAR_VALUE" ]; then
+  echo "Environment variable YARP_ROBOT_NAME is not set. Skipping post-commit hook."
+  exit 0
+fi
+
+# Get the current commit message
+CURRENT_COMMIT_MSG=$(git log -1 --pretty=%B)
+
+# Check if the commit message already starts with a [
+if [[ "$CURRENT_COMMIT_MSG" =~ ^\[ ]]; then
+  echo "Commit message already starts with '[', not modifying the commit message."
+  exit 0
+fi
+
+# Prepend the environment variable value to the commit message
+COMMIT_MSG_FILE=$(mktemp)
+echo "[$ENV_VAR_VALUE] $CURRENT_COMMIT_MSG" > "$COMMIT_MSG_FILE"
+
+# Amend the commit with the new message
+git -c core.hooksPath=/dev/null commit --amend -F "$COMMIT_MSG_FILE"
+
+# Clean up
+rm "$COMMIT_MSG_FILE"

.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+echo "Pre-commit hook running..."
+AUTHOR_IDENT=$(git var GIT_AUTHOR_IDENT | sed -r 's/( [^ ]+){2}$//')
+COMMITTER_IDENT=$(git var GIT_COMMITTER_IDENT | sed -r 's/( [^ ]+){2}$//')
+
+echo "Author identity: ${AUTHOR_IDENT}"
+echo "Committer identity: ${COMMITTER_IDENT}"
+
+if [ "${AUTHOR_IDENT}" == "${COMMITTER_IDENT}" ]; then
+  echo "Error! Author matched committer: this is not allowed."
+  echo "Please, use the option --author=\"Name Surnaname <[email protected]>\" to specify your identity."
+  exit 1  # Prevent the commit
+fi

.github/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+
+Contributing Guidelines
+=======================
+
+The main workflow we have to accept contributions is via [forks and pull-requests](https://guides.github.com/activities/forking).
+
+**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request)
+
+For specific robots that are intensively used by our Research Lines (e.g., `ergoCub`), we also consider the workflow described below. 
+
+# Easier management of `robots-configuration` on intensively used robots
+
+## 🔲 Intro
+The repository `robots-configuration` is maintained by iCub Tech and direct pushes are restricted to a few members of the facility, the rationale being that it would be very easy to mess it up otherwise. Thus, the current workflow dictates forking the repository and opening pull-requests frequently to merge changes upstream.
+
+Having said that, for robots that are being used by many users of different research lines and with a fast development pace (e.g., `ergoCub`), it turned out that it is somewhat inconvenient to rely on the present workflow. The main drawbacks are the following:
+1. To integrate changes, one developer needs to pass through a personal/organizational fork by switching the branch or copying out the relevant modifications elsewhere (e.g., on his/her system). Then, a wait state is introduced due to the PR review. Once done, it is finally required to update the local repository hosted on the robot system. Oftentimes, because this process tends to be long and cumbersome hence prone to oversights, changes are left uncommitted on the robot causing frustration among users who must deal with an untidy system.
+2. The process detailed on point 1 requires that the user is logged in. However, on the robot shared system, signing in on GitHub poses some difficulties mainly due to the 2FA, which eventually curbs the leaning to make contributions upstream.
+
+## 🔲 Fast-pace local workflow
+Here's the outline of the workflow that aims to overcome/attenuate the users' headaches:
+1. The organizational fork `icub-tech-iit/robots-configuration` is deployed on the robot system instead of the upstream repository `robotology/robots-configuration`.
+2. We set up the machine user [`icub-tech-iit-bot`](https://github.com/icub-tech-iit-bot) on the robot system as the default committer with push access, but only locally to the repository. Push access is granted via a fine-grained PAT.
+3. We enforce the use of `--author="Name Surnaname <[email protected]>"` command-line option (or the corresponding env variables) at commit time so that we can trace back who did what.
+4. As a result, on the robot system, users will work and be able to push to the branch `icub-tech-iit/robots-configuration@devel` (actually, we will have robot-specific branches, see below). Some sort of push limitations will be enforced on this branch: e.g., no push force.
+5. As it is paramount to enforce that at any time the configuration files allow the robot to start up flawlessly, there will be no specific automation aimed at synchronizing the upstream and the fork repositories back and forth. This process needs to be carried out under the supervision of educated humans.
+    1. **Human-supervised update fork → upstream**. It is performed periodically (e.g., every fortnight) via PR's. On the fork, the deal is that users will push only fixes (e.g., calibration values) and minor modifications (changing the options of some services) to the "official" robot files. Of course, users are free to deal with RL-specific additions/amendments. To facilitate integration, the PR's should be merged via `Rebase and Merge` to avoid this type of [problems](https://stackoverflow.com/questions/49200667/github-squash-and-merge-subsequent-pull-request-showing-all-previous-changes).
+    2. **Human-supervised update upstream → fork**. It is generally performed by iCub Tech developers (who keep on working upstream) when the time comes to perform tests on the robot. Once on the robot system, the developer will be using the fork, guaranteeing that the overall robot behavior won't be negatively affected by the latest modifications. Possible fixes pushed to the fork must be backed up upstream via PR's.
+6. To mitigate the effects of interaction among different robots, users will use robot-specific branches in the fork repository. In other words, for the `ergoCubSN???` robot, we will have, e.g., the `devel-ergoCubSN???` branch tracking the upstream devel.
+7. The maintainer of `robotology/robots-configuration` will possibly apply fixes received on the devel branch also to the master branch of the upstream repository.
+8. The new workflow is applied only internally to IIT and, to keep things simple, only to robot systems that are used intensively: i.e., `ergoCubSN00???`.
+
+## 🔲 [Technicalities](./local-workflow-tech.md)

.github/local-workflow-tech.md

@@ -0,0 +1,95 @@
+Technicalities underlying the fast-pace local workflow
+======================================================
+
+## 🔲 Set up the options of the fork repository
+- Create a ruleset that:
+  - Targets all branches.
+  - Restricts updates.
+  - Restricts deletions.
+  - Blocks force pushes.
+- Disable the option `Automatically delete head branches`.
+
+## 🔲 Clone the fork locally
+- Clone the `icub-tech-iit` fork:
+  ```console
+  git remote add icub-tech https://github.com/icub-tech-iit/robots-configuration.git
+  ```
+- Switch to the branch corresponding to the robot (e.g., `devel-ergoCubSN???`).
+
+## 🔲 Set the default committer
+- Fine-grained PAT can be scoped to work on a specified organization and only on a specified repository.
+- To store credentials locally, one needs to issue the following, once the fork is cloned locally:
+  ```console
+  git config --local user.name "icub-tech-iit-bot"
+  git config --local user.email "[email protected]"
+  git config --local credential.https://github.com/icub-tech-iit/robots-configuration.git.helper store
+  ```
+  ⚠️ Note the use of the option `--local` to avoid impacting Git globally on the system.
+- In order to push without password, the PAT needs to be provided. The credentials will be stored plainly under `~/.git-credentials`. No worries though, as this PAT has a very narrowed use and impacts a fork that is backed up anyhow by the upstream repository.
+- The PAT can be stored manually in `~/.git-credentials` with the format `https://icub-tech-iit-bot:${PAT}@github`. Alternatively, when attempting to push the first time, it is enough to use `icub-tech-iit-bot` as user and specifying the `PAT` as password. This will be stored in the `~/.git-credentials` file automatically.
+- ⚠️  Being the local system shared, no one else should store his/her PAT in the same file.
+- The PAT is set to have no expiration. However, it can be revoked at any time by the maintainer.
+
+> [!tip]
+> Instead of relying on the credential helper, one can resort to a simpler method:
+> ```console
+> git remote set-url icub-tech https://x-access-token:${PAT}@github.com/icub-tech-iit/robots-configuration.git
+> ```
+
+## 🔲 Ensure that the author information is specified explicitly at commit time
+- We do rely on [Git hoooks](../.githooks).
+- Run the following command from the `robots-configuration` root folder:
+  ```console
+  git config --local core.hooksPath .githooks/
+  ```
+
+# 🔘 Use an external robots-configuration separately from `robotology-superbuild`
+
+In some `ergoCubSN???` setups, the `robots-configuration` used by the robot is not the one downloaded by the `robotology-superbuild` (that would be found at `/usr/local/src/robot/robotology-superbuild/src/robots-configuration`),
+but rather a separate `robots-configuration` available at `/usr/local/src/robot/robots-configuration`. This is done for two reasons:
+- To permit to clone a fresh new `robotology-superbuild`, without the need to manually perform the local repository configuration as described in the previous section,
+- To permit to easily share the used `robots-configuration` to other `robotology-superbuild`, that for example are part of a different environment or a different container.
+
+The steps necessary to switch to use an external robots-configuration given an existing `robotology-superbuild` setup are the following:
+
+## 🔲 Disable robots-configuration from the superbuild
+
+First of all, pass the [`-ROBOTOLOGY_SKIP_ROBOTS_CONFIGURATION:BOOL=ON`](https://github.com/robotology/robotology-superbuild/pull/1775) CMake option to all the `robotology-superbuild` that should use the external `robots-configuration`.
+
+If the `robotology-superbuild` was already built once, remember to first uninstall and then delete the existing robots-configuration repository to avoid confusion.
+
+In particular uninstall with:
+
+```console
+cd /usr/local/src/robot/robotology-superbuild/build/src/robots-configuration
+make uninstall
+```
+
+and delete any `robots-configuration` folder with:
+
+```console
+cd /usr/local/src/robot/robotology-superbuild
+rm -rf /usr/local/src/robot/robotology-superbuild/src/robots-configuration
+rm -rf /usr/local/src/robot/robotology-superbuild/build/src/robots-configuration
+```
+
+## 🔲 Clone, install and ensure that external robots-configuration is visible
+
+```console
+cd /usr/local/src/robot
+git clone  https://github.com/robots-configuration/robots-configuration.git
+cd robots-configuration
+```
+
+At this point, follow the configuration steps documented in the earlier section. Then, install the repo without dependencies, using the `nodeps` CMake preset:
+
+```console
+cmake --preset nodeps
+cmake --install build
+```
+
+After you did all of this, to ensure that the installed files are found by YARP, add the following line to the `.bashrc_iCub` of the robot:
+
+```console
+export YARP_DATA_DIRS=$YARP_DATA_DIRS:/usr/local/src/robot/robots-configuration/build/install/share/ICUBcontrib
+```

.github/workflows/ci-nodeps.yml

@@ -0,0 +1,44 @@
+name: CI Workflow with nodeps CMake preset
+
+on:
+  push:
+    branches:
+    - 'master'
+    - 'devel'
+    paths-ignore:
+      - 'experimentalSetups/**'
+      - 'iCubTemplates/**'
+      - 'tests/**'
+      - '.github/**'
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+    paths-ignore:
+      - 'experimentalSetups/**'
+      - 'iCubTemplates/**'
+      - 'tests/**'
+      - '.github/**'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install deps
+      run: |
+        sudo apt install -y cmake build-essential
+
+    - name: Configure
+      run: |
+        cmake --preset nodeps
+
+    - name: Build
+      run: |
+        cmake --build --preset nodeps
+
+    - name: Install
+      run: |
+        cd build
+        cmake --install .

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI Workflow
+
+on:
+  push:
+    branches:
+    - 'master'
+    - 'devel'
+    paths-ignore:
+      - 'experimentalSetups/**'
+      - 'iCubTemplates/**'
+      - 'tests/**'
+      - '.github/**'
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+    paths-ignore:
+      - 'experimentalSetups/**'
+      - 'iCubTemplates/**'
+      - 'tests/**'
+      - '.github/**'
+  workflow_dispatch:
+
+env:
+  DEPENDENCIES_DIR: '/dependencies'
+
+jobs:
+  dry-run:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/robotology/robots-configuration:latest
+
+    steps:
+    - uses: actions/checkout@main
+
+    - name: Extend environment
+      shell: bash
+      run: |
+        echo "${DEPENDENCIES_DIR}/install/bin" >> $GITHUB_PATH
+        echo "YARP_DATA_DIRS=${DEPENDENCIES_DIR}/install/share/yarp:${DEPENDENCIES_DIR}/install/share/iCub:${DEPENDENCIES_DIR}/install/share/CER:${DEPENDENCIES_DIR}/install/share/navigation:${DEPENDENCIES_DIR}/install/share/ICUBcontrib" >> $GITHUB_ENV
+
+    - name: Configure Tests
+      shell: bash
+      run: |
+        cd ./tests/dry-run/
+        ./configure-tests.sh
+
+    - name: Tests
+      shell: bash
+      run: |
+        cd ./tests/dry-run/build
+        ctest --timeout 60 --output-on-failure -L run
+
+    - name: Upload Output
+      if: always()
+      uses: actions/upload-artifact@main
+      with:
+        name: dry-run_${{ github.run_id }}
+        path: tests/dry-run/build/dry-run_log_*.txt
+        retention-days: 30

.github/workflows/nightly-merge.yml

@@ -10,15 +10,13 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v1
+      uses: actions/checkout@main
 
     - name: Nightly Merge
-      uses: robotology/gh-action-nightly-merge@v1.2.0
+      uses: robotology/gh-action-nightly-merge@master
       with:
         stable_branch: 'master'
         development_branch: 'devel'
         allow_ff: true
-        push_token: 'marcoaccame_TOKEN'
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        marcoaccame_TOKEN: ${{ secrets.marcoaccame_TOKEN }}

.github/workflows/publish-docker.yml

@@ -0,0 +1,31 @@
+name: Publish Docker Image
+
+on:
+  workflow_dispatch:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@main
+    - name: Publish to Registry
+      uses: elgohr/Publish-Docker-Github-Action@v5
+      env:
+        DEPENDENCIES_DIR: '/dependencies'
+      with:
+        name: robotology/robots-configuration
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+        workdir: tests/dockerfiles
+        buildargs: DEPENDENCIES_DIR
+        registry: ghcr.io
+        tags: "latest"
+    - name: Clean up Registry from untagged images
+      uses: actions/delete-package-versions@v5
+      with: 
+        package-name: 'robots-configuration'
+        package-type: 'container'
+        min-versions-to-keep: 0
+        delete-only-untagged-versions: "true"

.gitignore

@@ -1,5 +1,5 @@
 # Build products
-/build*/
+build*
 
 # System hidden files
 .DS_Store