Add the fast-pace local workflow

.githooks/pre-commit

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# Get author and committer details
+AUTHOR_NAME=$(git log -1 --format="%an")
+AUTHOR_EMAIL=$(git log -1 --format="%ae")
+COMMITTER_NAME=$(git config user.name)
+COMMITTER_EMAIL=$(git config user.email)
+
+# Check for identity match
+if [ "$AUTHOR_NAME" = "$COMMITTER_NAME" ] || [ "$AUTHOR_EMAIL" = "$COMMITTER_EMAIL" ]; then
+  echo "Error: author information is missing."
+  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,34 @@
+
+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.
+    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 will need to be backed up upstream via PR's.
+    3. This way, there may exist the possibility that the upstream and the fork devel branches diverge generating conflicts that are discovered too late. To remedy this, an automation (i.e., a GitHub action running on the fork) will be responsible for checking the presence of conflicts between the two branches at push time. If something relevant gets detected, the push author and the upstream maintainer will be notified through an automatically generated issue so that an action can be undertaken timely.
+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,27 @@
+Technicalities underlying the fast-pace local workflow
+======================================================
+
+## 🔲 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.helper store
+  ```
+  ⚠️ Note the use of the option `--local` to avoid impacting Git globally on the system.
+- The first time there's a push, the PAT needs to be provided. The credentials will be stored plainly under `~/.git-credentials` (the format is: `https://<username>:ghp_...`). 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 in `~/.git-credentials` upfront as well.
+- ⌛ The PAT expires after **`1 year`** at the latest, thus needing to be regenerated.
+- The upstream maintainer will take care of the PAT.
+
+## 🔲 Ensure that the author information is specified explicitly at commit time
+- We do rely on [Git hoooks](../.githooks).
+- After cloning the fork locally, issue:
+  ```console
+  git config --local core.hooksPath .githooks/
+  ```
+
+## 🔲 Detect conflicts at push time and notify PIC
+
+> [!note]
+> To be still developed.

README.md

@@ -46,10 +46,7 @@ yarp-config robot --import $YARP_ROBOT_NAME
 
 You should end up finding the local copies under `~/.local/share/yarp/robots/$YARP_ROBOT_NAME`.
 
-## Contributing
-We accept contributions 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)
+## [Contributing](./.github/CONTRIBUTING.md)
 
 ## License
 Material included here is Copyright of _iCub Facility - Istituto Italiano di