docs: improve conributing guide and fix linux developer setup script

.gitignore

@@ -11,5 +11,6 @@ git_hash.txt
 
 /.coverage
 venv/
+.venv/
 test.txt
 test.xml

CONTRIBUTING.md

@@ -14,25 +14,94 @@ Possible ways you can help:
 * Reviewing [existing pull requests](https://github.com/ArduPilot/MethodicConfigurator/pulls), and notifying the maintainer if it passes your code review.
 * Finding and fixing [security issues](SECURITY.md)
 
-Get the code with:
+## Learning the Code
 
-```bash
-git clone https://github.com/ArduPilot/MethodicConfigurator.git
-cd MethodicConfigurator
-```
-
-and read [our architecture](https://ardupilot.github.io/MethodicConfigurator/ARCHITECTURE.html) to get a better understanding of the project.
+Read [our architecture](https://ardupilot.github.io/MethodicConfigurator/ARCHITECTURE.html) to get a better understanding of the project.
 
 and also:
 
 * [System requirements](https://ardupilot.github.io/MethodicConfigurator/SYSTEM_REQUIREMENTS.html)
 * [Compliance](https://ardupilot.github.io/MethodicConfigurator/COMPLIANCE.html)
 
+## Setting up developer environment
+
+1. [Install git](https://git-scm.com/install/) on your computer.
+2. Create a free [personal github account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github)
+3. [Log in to your github account](https://github.com/login) using a browser
+4. [Fork the ArduPilot/MethodicConfigurator github repository](https://github.com/ArduPilot/MethodicConfigurator/fork).
+5. Clone your fork and navigate into it:
+
+    ```bash
+    git clone https://github.com/YOUR_USER_NAME/MethodicConfigurator.git
+    cd MethodicConfigurator
+    ```
+
+6. Run the following helper scripts:
+
+    On Windows:
+
+    ```powershell
+    .\SetupDeveloperPC.bat
+    ```
+
+    On Linux and macOS:
+
+    ```bash
+    ./SetupDeveloperPC.sh
+    ```
+
+The above scripts will:
+
+* Configure Git and useful aliases
+* Create a Python virtual environment and install project dependencies
+* Install recommended VSCode extensions
+* Set up pre-commit hooks for linting and formatting
+* Install GNU gettext tools for internationalization support
+
+## Executing the code
+
+You can either install the Methodic Configurator as a package or run it locally from your development codebase.
+Installing the package will fetch the latest stable release version — see the [installation guide](https://ardupilot.github.io/MethodicConfigurator/INSTALL.html) for details.
+
+To run it locally (from your cloned repository):
+
+On Windows:
+
+```powershell
+.venv\Scripts\activate.ps1
+python3 -m ardupilot_methodic_configurator
+```
+
+On macOS & Linux:
+
+```bash
+source .venv/bin/activate
+python3 -m ardupilot_methodic_configurator
+```
+
+More detailed usage instructions can be found in our [user manual](https://ardupilot.github.io/MethodicConfigurator/USERMANUAL)
+
 ## Submitting patches
 
-Please see our [wiki article](https://ardupilot.org/dev/docs/submitting-patches-back-to-master.html).
+Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style for your git commit messages.
+
+Each commit should be signed off using the `--signoff` option in `git commit`.
+By signing off your commit, you certify that you agree to the terms of the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).
+
+You can sign by either your commit by pressing the *sign-off* button on `git gui` or by using the command line:
+
+```bash
+# Sign off a commit as you're making it
+git commit --signoff -m "commit message"
+
+# Add a signoff to the last commit you made
+git commit --amend --signoff
+
+# Rebase your branch against master and sign off every commit in your branch
+git rebase --signoff master
+```
 
-To contribute, you can send a [pull request on GitHub](https://github.com/ArduPilot/MethodicConfigurator/pulls).
+Once your changes are ready, submit a [GitHub Pull Request (PR)](https://github.com/ArduPilot/MethodicConfigurator/pulls).
 
 ## Development Team
 

INSTALL.md

@@ -95,8 +95,8 @@ You need to create and activate a new virtual environment before you can run the
 sudo apt install python3-tk
 python -m venv .ardupilot_methodic_configurator_venv
 source .ardupilot_methodic_configurator_venv/bin/activate
-python -m pip install --upgrade pip
-pip install ardupilot_methodic_configurator
+python -m pip install uv
+uv pip install ardupilot_methodic_configurator
 ```
 
 To run it, execute the command line:

SetupDeveloperPC.bat

@@ -1,6 +1,8 @@
 @echo off
 setlocal enabledelayedexpansion
 
+:: Configure a Microsoft Windows developer PC for ArduPilot Methodic Configurator development.
+
 :: Store the original directory
 set "ORIGINAL_DIR=%CD%"
 
@@ -48,18 +50,45 @@ if "!found!"=="0" (
 
 :checkDone
 
+:: Create a local virtual environment if it doesn't exist
+if not exist ".venv" (
+    echo Creating Python virtual environment...
+    python -m venv .venv
+)
+
+:: Activate the virtual environment
+echo Activating virtual environment...
+call .venv\Scripts\activate.bat
 
+call :InstallDependencies
 call :ConfigureArgComplete
 call :ConfigureGit
 call :ConfigureVSCode
 call :ConfigurePreCommit
+call :InstallMsgfmt
 
 echo running pre-commit checks on all Files
 pre-commit run -a
 
 :: Change back to the original directory
 cd /d %ORIGINAL_DIR%
 
+echo.
+echo To run the ArduPilot methodic configurator GUI, execute the following commands:
+echo.
+echo .venv\Scripts\activate.ps1
+echo python3 -m ardupilot_methodic_configurator
+echo.
+echo If you encounter issues with auto-connecting to the wrong device on MS Windows,
+echo you can explicitly set the device with the --device command line option:
+echo.
+echo python3 -m ardupilot_methodic_configurator --device COMX
+echo.
+echo Replace COMX with the correct COM port for your device.
+echo.
+echo For more detailed usage instructions, please refer to the USERMANUAL.md file.
+echo.
+
 echo Script completed successfully.
 exit /b
 
@@ -85,7 +114,6 @@ git config --local alias.cm "commit -m"
 git config --local alias.pom "push origin master"
 git config --local alias.aa "add --all"
 git config --local alias.df diff
-git config --local alias.su "submodule update --init --recursive"
 git config --local credential.helper manager
 git config --local pull.rebase true
 git config --local push.autoSetupRemote
@@ -208,3 +236,14 @@ if !ERRORLEVEL! equ 0 (
 )
 
 goto :eof
+
+:InstallMsgfmt
+echo Installing GNU gettext tools (msgfmt)...
+call install_msgfmt.bat
+goto :eof
+
+:InstallDependencies
+echo Installing project dependencies...
+python -m pip install uv
+uv pip install -e .[dev]
+goto :eof

SetupDeveloperPC.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 #
+# Configure a Linux or macOS developer PC for ArduPilot Methodic Configurator development.
+#
 # SPDX-FileCopyrightText: 2024-2025 Amilcar do Carmo Lucas <amilcar.lucas@iav.de>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
@@ -21,24 +23,47 @@ ORIGINAL_DIR=$(pwd)
 # Change to the directory where the script resides
 cd "$(dirname "$0")" || exit
 
+# Install macOS dependencies early if on macOS
+if command -v brew &> /dev/null; then
+    echo "Installing macOS dependencies with Homebrew..."
+    brew install uv python-tk@3.9
+    echo "Creating Python virtual environment with uv..."
+    uv venv --python 3.9
+else
+    # Create a local virtual environment if it doesn't exist
+    if [ ! -d ".venv" ]; then
+        echo "Creating Python virtual environment..."
+        python3 -m venv .venv
+    fi
+fi
+
+# Activate the virtual environment
+echo "Activating virtual environment..."
+# shellcheck disable=SC1091
+source .venv/bin/activate
+
 InstallDependencies() {
     echo "Updating package lists..."
     if command -v apt-get &> /dev/null; then
         sudo apt-get update
         # Install Python3 PIL.ImageTk for GUI support
         echo "Installing Python3 PIL.ImageTk..."
-        sudo apt-get install -y python3-pil.imagetk
+        sudo apt-get install -y python3-pil.imagetk gettext
+        python3 -m pip install uv
+    elif command -v brew &> /dev/null; then
+        echo "macOS dependencies already installed."
     else
-        echo "apt-get not found. Skipping system package updates."
+        echo "Neither apt-get nor brew found. Please install dependencies manually."
     fi
 
+    # No need to uninstall serial and pyserial anymore as the virtual environment is isolated
     # Uninstall serial and pyserial to avoid conflicts
-    echo "Uninstalling serial and pyserial..."
-    sudo python3 -m pip uninstall -y serial pyserial
+    # echo "Uninstalling serial and pyserial..."
+    # uv pip uninstall -y serial pyserial
 
     # Install the project dependencies
     echo "Installing project dependencies..."
-    python3 -m pip install -e .[dev]
+    uv pip install -e .[dev]
 }
 
 ConfigureGit() {
@@ -63,7 +88,6 @@ ConfigureGit() {
     git config --local alias.pom "push origin master"
     git config --local alias.aa "add --all"
     git config --local alias.df diff
-    git config --local alias.su "submodule update --init --recursive"
     git config --local credential.helper manager
     git config --local pull.rebase true
     git config --local push.autoSetupRemote
@@ -109,6 +133,24 @@ ConfigureVSCode() {
             exit 1
         fi
 
+        echo "Installing code spellcheker extension..."
+        if ! code --install-extension streetsidesoftware.code-spell-checker; then
+            echo "Failed to install code spellcheker extension."
+            exit 1
+        fi
+
+        echo "Installing the Python VSCode extension..."
+        if ! code --install-extension ms-python.python; then
+            echo "Failed to install Python VSCode extension."
+            exit 1
+        fi
+
+        echo "Installing ruff extension..."
+        if ! code --install-extension charliermarsh.ruff; then
+            echo "Failed to install ruff extension."
+            exit 1
+        fi
+
     fi
 }
 
@@ -128,5 +170,14 @@ pre-commit run -a
 # Change back to the original directory
 cd "$ORIGINAL_DIR" || exit
 
+echo ""
+echo "To run the ArduPilot methodic configurator GUI, execute the following commands:"
+echo ""
+echo "source .venv/bin/activate"
+echo "python3 -m ardupilot_methodic_configurator"
+echo ""
+echo "For more detailed usage instructions, please refer to the USERMANUAL.md file."
+echo ""
+
 echo "Script completed successfully."
 exit 0