feat: release 2.8.20

Author: jmrenouard

.agent/rules/01_objective.md

@@ -12,3 +12,12 @@ $$DYNAMIC\_CONTEXT$$
 3. **Docs:** Keep `README.md` and translations updated with new features and requirements.
 4. **Automation:** All tests runnable via `make test-*` or specific test scripts.
 5. **Goal:** Provide the most accurate and up-to-date performance tuning recommendations for MySQL-compatible databases.
+
+**Roadmap / Evolution Paths:**
+
+1. **Schema Validation for Rules**: Créer un script de linting pour valider que les fichiers `.agent/rules/*.md` respectent un format standard.
+2. **Source Code Annotation**: Automatiser l'ajout des tags de version directement dans les commentaires des fonctions modifiées.
+3. **Automated Doc-Link Check**: Ajouter un test qui vérifie que les liens de documentation insérés dans les commentaires du code (`# See: http://...`) sont toujours valides.
+4. **Pre-commit Hook**: Implementer un hook Git local qui lance le pre-flight check de `/git-flow`.
+5. **Automated Roadmap Tracking**: Créer un script qui extrait les points de la roadmap pour générer un rapport de progression.
+6. **Perl Tidy Integration**: Ajouter une règle exigeant l'utilisation de `perltidy` avec une configuration spécifique pour garantir la lisibilité du fichier unique.

.agent/rules/03_execution_rules.md

@@ -19,7 +19,17 @@ trigger: always_on
 - **DRY (Don't Repeat Yourself)**: Avoid code duplication; extract common logic into reusable functions within the single file.
 - **KISS (Keep It Simple, Stupid)**: Strive for simplicity. Avoid over-engineering.
 - **Clean Code**: Write readable, self-documenting code with meaningful names and small functions.
-- **Error Handling**: Implement robust error handling and logging. Use low-cardinality logging with stable message strings (e.g., `logger.info{id, foo}, 'Msg'`).
+- **Perl Tidy**: Use `perltidy` with the project's specific configuration to ensure consistent formatting across the single-file architecture.
+- **Error Handling**: Implement robust error handling and logging. Use low-cardinality logging with stable message strings.
+
+#### **Core Best Practices:**
+
+1. **Validation Multi-Version Systématique**: Tout changement dans la logique de diagnostic doit être testé contre au moins une version "Legacy" (ex: MySQL 5.7) et une version "Moderne" (ex: MariaDB 11.4) via la suite de tests Docker (`make test-it`).
+2. **Résilience des Appels Système**: Chaque commande externe (`sysctl`, `ps`, `free`, `mysql`) doit impérativement être protégée par une vérification de l'existence du binaire et une gestion d'erreur (exit code non nul) pour éviter les sorties "polluées" dans le rapport final.
+3. **Politique "Zéro-Dépendance" CPAN**: Interdire l'usage de modules Perl qui ne font pas partie du "Core" (distribution standard Perl) afin que `mysqltuner.pl` reste un script unique, copiable et exécutable instantanément sur n'importe quel serveur sans installation préalable.
+4. **Traçabilité des Conseils (Audit Trail)**: Chaque recommandation ou conseil affiché par le script doit être documenté dans le code par un commentaire pointant vers la source officielle (Documentation MySQL/MariaDB ou KB) pour justifier le seuil choisi.
+5. **Efficience Mémoire (Parsing de Log)**: Pour le traitement des fichiers de logs (souvent volumineux), privilégier systématiquement le traitement ligne par ligne plutôt que le chargement complet en mémoire, surtout lors de la récupération via `--container`.
+6. **Standardisation @Changelog**: Maintenir le `@Changelog` en suivant strictement le format des _Conventional Commits_ (feat, fix, chore, docs) pour permettre une extraction automatisée et propre des notes de version lors des tags Git.
 
 ### **4.3. Output & Restitution Format**
 
@@ -31,11 +41,12 @@ trigger: always_on
 ### **4.4. Development Workflow**
 
 1. **Validation by Proof:** All changes must be verifiable via `make test-*` or dedicated test scripts.
-2. **Git Protocol:**.
-/!\ NOT COMMIT, NO TAG CODE UNLESS USING /git-flow or explicit order
-Use **Conventional Commits** (feat:, fix:, chore:, docs:).
-WARNING: Don't increment version in changelog or script if code is not tagged and pushed
-If last tag is not remotely present, don't increment version unless explicitly asked
-Commit and tag should be done together
-
-3. **Changelog:** All changes MUST be traced and documented inside `@Changelog`.
+2. **Git Protocol:**
+
+- **STRICT PROHIBITION:** No `git commit`, `git push`, or `git tag` without using `/git-flow` or an explicit user order.
+- **Conventional Commits:** Use `feat:`, `fix:`, `chore:`, `docs:`.
+- **Versioning & Tagging:** Reserved ONLY for the `/git-flow` workflow.
+- **Atomic Operations:** Commit and tag must be synchronized via the workflow.
+- **Remote Sync:** If the last tag is not present on remote, do not increment version without explicit confirmation.
+
+1. **Changelog:** All changes MUST be traced and documented inside `@Changelog`.

.agent/rules/04_memory_protocol.md

@@ -15,9 +15,9 @@ Changelog last version
 2. **Git Sync:** Consult git log \-n 15 to synchronize context.  
 3. **Rotation:** FIFO Rotation (Max 600 lines). Remove oldest entries beyond 600 lines.
 
-4. All changes must be added to last version
-5. No Increment version if explicit git commit/tag/push via /git-flow or specific order from previous version has'nt been made
-After Git tag and push, increment version on last digit  
+4. All changes must be added to last version in `Changelog`.
+5. No increment version if explicit git commit/tag/push via `/git-flow` or specific order from previous version hasn't been made.
+6. After Git tag and push, increment version on last digit for the next development cycle.
 
 ### **History Entry example**
 

.agent/workflows/git-flow.md

@@ -2,53 +2,79 @@
 description: Automate git-flow release process
 ---
 
-1. **Ensure clean working tree**
+1. **Ensure clean working tree and Pre-flight Consistency Check**
+   - Verify that `Changelog`, `CURRENT_VERSION.txt`, and `mysqltuner.pl` are synchronized.
 
    ```bash
    git status --porcelain
+   CURRENT_VER=$(cat CURRENT_VERSION.txt | tr -d '[:space:]')
+   SCRIPT_VER=$(grep "my \$tunerversion =" mysqltuner.pl | cut -d'"' -f2)
+   CHANGELOG_VER=$(head -n 1 Changelog | awk '{print $1}')
+
+   echo "Checking version consistency: $CURRENT_VER"
+   
+   if [ "$CURRENT_VER" != "$SCRIPT_VER" ]; then
+       echo "ERROR: CURRENT_VERSION.txt ($CURRENT_VER) does not match mysqltuner.pl ($SCRIPT_VER)"
+       exit 1
+   fi
+
+   if [ "$CURRENT_VER" != "$CHANGELOG_VER" ]; then
+       echo "ERROR: CURRENT_VERSION.txt ($CURRENT_VER) does not match Changelog ($CHANGELOG_VER)"
+       exit 1
+   fi
+   
+   echo "Consistency check passed."
    ```
 
    // turbo
-2. **Update version**
-   - Increment patch version in `CURRENT_VERSION.txt` (e.g., `1.0.9` → `1.0.10`).
-   - Update `$tunerversion` variable in `mysqltuner.pl` header.
+2. **Commit Current Changes**
+   - Commit all pending changes including `Changelog` updates for the current version.
 
    ```bash
-   NEW_VER=$(awk -F. '{print $1"."$2"."($3+1)}' CURRENT_VERSION.txt)
-   echo $NEW_VER > CURRENT_VERSION.txt
-   sed -i "s/\$tunerversion = .*/\$tunerversion = \"$NEW_VER\";/" mysqltuner.pl
+   git add .
+   git commit -m "feat: release $CURRENT_VER"
    ```
 
    // turbo
-3. **Update Changelog**
-   - Prepend entry with new version and date.
+3. **Create Tag for Current Version with Changelog content**
+   - Extract the latest release notes and create an annotated tag.
 
    ```bash
-   DATE=$(date +%Y-%m-%d)
-   echo "$NEW_VER $DATE" > tmp_changelog && cat Changelog >> tmp_changelog && mv tmp_changelog Changelog
+   # Extract content between the first version header and the next one
+   TAG_MSG=$(awk "/^$CURRENT_VER/,/^([0-9]+\.[0-9]+\.[0-9]+)/ {if (\$0 !~ /^([0-9]+\.[0-9]+\.[0-9]+)/) print}" Changelog | sed '/^$/d')
+   git tag -a v$CURRENT_VER -m "Release $CURRENT_VER" -m "$TAG_MSG"
    ```
 
    // turbo
-4. **Commit changes**
+4. **Push Branch and Tag**
+   - Push to the remote repository.
 
    ```bash
-   git add CURRENT_VERSION.txt mysqltuner.pl Changelog
-   git commit -m "feat: release $NEW_VER"
+   git push origin main
+   git push origin v$CURRENT_VER
    ```
 
    // turbo
-5. **Create tag**
+5. **Post-Push: Increment Version for Next Cycle**
+   - Calculate the next patch version and update files.
 
    ```bash
-   git tag -a v$NEW_VER -m "Release $NEW_VER"
+   NEW_VER=$(echo $CURRENT_VER | awk -F. '{print $1"."$2"."($3+1)}')
+   echo $NEW_VER > CURRENT_VERSION.txt
+   sed -i "s/my \$tunerversion = .*/my \$tunerversion = \"$NEW_VER\";/" mysqltuner.pl
+   
+   DATE=$(date +%Y-%m-%d)
+   echo -e "$NEW_VER $DATE\n\n- \n" > tmp_changelog && cat Changelog >> tmp_changelog && mv tmp_changelog Changelog
    ```
 
    // turbo
-6. **Push branch and tags**
+6. **Commit Version Bump**
+   - Commit the incremented version for the next development cycle.
 
    ```bash
+   git add CURRENT_VERSION.txt mysqltuner.pl Changelog
+   git commit -m "chore: bump version to $NEW_VER"
    git push origin main
-   git push origin v$NEW_VER
    ```
 
    // turbo

.agent/workflows/git-rollback.md

@@ -0,0 +1,37 @@
+---
+description: Rollback a failed release (delete tags and revert commits)
+---
+
+1. **Delete Local and Remote Tag**
+   - Identify the tag to remove from `CURRENT_VERSION.txt`.
+
+   ```bash
+   VERSION_TO_ROLLBACK=$(cat CURRENT_VERSION.txt)
+   echo "Rolling back version v$VERSION_TO_ROLLBACK"
+   
+   git tag -d v$VERSION_TO_ROLLBACK
+   git push --delete origin v$VERSION_TO_ROLLBACK
+   ```
+
+   // turbo
+2. **Revert Release Commits**
+   - Reset the branch to the state before the release commit.
+   - **WARNING**: This uses `git reset --hard`. Ensure you don't have uncommitted work you want to keep.
+
+   ```bash
+   # Identify the commit before the release commit (assuming the last commit was the version bump)
+   # We might want to revert the last 2 commits: the bump and the release tag commit.
+   
+   # Reset to 2 commits ago
+   git reset --hard HEAD~2
+   
+   # Force push to clean remote main branch
+   # git push origin main --force
+   ```
+
+   // turbo
+3. **Notify User**
+   - The rollback is completed locally. Remote sync may require a force push.
+
+   > [!CAUTION]
+   > The local branch has been reset. If you had already pushed the version bump, you may need to run `git push origin main --force` to synchronize the remote branch.

CURRENT_VERSION.txt

@@ -1 +1 @@
-2.8.19
+2.8.20

Changelog

@@ -1,6 +1,7 @@
-2.8.19 2026-01-18
+2.8.20 2026-01-18
 
-- feat: release 2.8.19
+- feat: add automated regression test for forcemem MB interpretation (issues #780, #810)
+- chore: bump version to 2.8.20
 
 2.8.18 2026-01-18
 

mysqltuner.pl

@@ -59,7 +59,7 @@ package main;
 my $is_win = $^O eq 'MSWin32';
 
 # Set up a few variables for use in the script
-my $tunerversion = "2.8.19";
+my $tunerversion = "2.8.20";
 my ( @adjvars, @generalrec );
 
 # Set defaults
@@ -8220,7 +8220,7 @@ sub dump_csv_files {
 
 =head1 NAME
 
- MySQLTuner 2.8.10 - MySQL High Performance Tuning Script
+ MySQLTuner 2.8.20 - MySQL High Performance Tuning Script
 
 =head1 IMPORTANT USAGE GUIDELINES
 

tests/test_forcemem.t

@@ -0,0 +1,65 @@
+use strict;
+use warnings;
+use Test::More;
+
+# Mocking variables from mysqltuner.pl
+our %opt;
+our $physical_memory;
+our $swap_memory;
+
+sub infoprint { } # Silence output
+sub badprint { }
+sub debugprint { }
+
+sub hr_bytes {
+    my $num = shift;
+    return "0B" unless defined($num);
+    if ( $num >= ( 1024**3 ) ) { return sprintf( "%.1f", ( $num / ( 1024**3 ) ) ) . "G"; }
+    elsif ( $num >= ( 1024**2 ) ) { return sprintf( "%.1f", ( $num / ( 1024**2 ) ) ) . "M"; }
+    elsif ( $num >= 1024 ) { return sprintf( "%.1f", ( $num / 1024 ) ) . "K"; }
+    else { return $num . "B"; }
+}
+
+sub os_setup_logic {
+    my ($os, $opt_forcemem, $opt_forceswap) = @_;
+    
+    # Logic from mysqltuner.pl
+    if ( $opt_forcemem > 0 ) {
+        $physical_memory = $opt_forcemem * 1048576;
+        if ( $opt_forceswap > 0 ) {
+            $swap_memory = $opt_forceswap * 1048576;
+        } else {
+            $swap_memory = 0;
+        }
+    } else {
+        # Mocked system detection
+        $physical_memory = 2048 * 1048576; # 2GB
+        $swap_memory = 1024 * 1048576; # 1GB
+    }
+    
+    # Regression check for v2.6.1 bug: 
+    # $physical_memory = $opt_forcemem if ($opt_forcemem > 0); 
+    # This line IS DELETED in current version.
+    
+    return ($physical_memory, $swap_memory);
+}
+
+# Test cases
+my ($mem, $swap);
+
+# 32GB requested via forcemem
+($mem, $swap) = os_setup_logic("Linux", 32768, 0);
+is($mem, 34359738368, "32768 MB should be 34359738368 bytes");
+is(hr_bytes($mem), "32.0G", "32768 MB should be displayed as 32.0G");
+
+# 1GB requested via forcemem
+($mem, $swap) = os_setup_logic("Linux", 1024, 0);
+is($mem, 1073741824, "1024 MB should be 1073741824 bytes");
+is(hr_bytes($mem), "1.0G", "1024 MB should be displayed as 1.0G");
+
+# 2000 MB requested (issue #780)
+($mem, $swap) = os_setup_logic("Linux", 2000, 0);
+is($mem, 2097152000, "2000 MB should be 2097152000 bytes");
+is(hr_bytes($mem), "2.0G", "2000 MB should be displayed as 2.0G (not 2.0K)");
+
+done_testing();