From 282dcb28f46f9b8e1aca09258f28fe8076614270 Mon Sep 17 00:00:00 2001
From: Jeremy Lecour <jlecour@evolix.fr>
Date: Tue, 20 Feb 2024 18:50:34 +0100
Subject: [PATCH] apt: add comments to deb822 migration scripts

---
 apt/files/deb822-migration.py | 15 +++++++++++++++
 apt/files/deb822-migration.sh |  8 +++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/apt/files/deb822-migration.py b/apt/files/deb822-migration.py
index 96ef1721..cb135972 100755
--- a/apt/files/deb822-migration.py
+++ b/apt/files/deb822-migration.py
@@ -1,5 +1,11 @@
 #!/usr/bin/env python3
 
+##########
+# This script takes a multi-lines input of "oneliner-style" APT sources definitions.
+# It converts them into "deb822-style" sources.
+# Each generated file will have only one stanza, possibly with multiple Types/Suites/Components
+##########
+
 import re
 import sys
 import os
@@ -10,12 +16,16 @@ import apt_pkg
 # Order matters !
 destinations = {
     "debian-security": "security.sources",
+
     ".*-backports": "backports.sources",
+
     ".debian.org": "system.sources",
     "mirror.evolix.org": "system.sources",
     "ftp.evolix.org": "system.sources",
+
     "pub.evolix.net": "evolix_public_old.sources.bak",
     "pub.evolix.org": "evolix_public.sources",
+
     "artifacts.elastic.co": "elastic.sources",
     "download.docker.com": "docker.sources",
     "downloads.linux.hpe.com": "hp.sources",
@@ -77,6 +87,11 @@ def prepare_sources(lines):
                         key, value = option.split("=")
                         options[key] = value
 
+            ### WARNING ###
+            # if there are multiple lines with different URIS for a given destination (eg. "system")
+            # each one will overwrite the previous one 
+            # and the last evaluated will be what remains.
+
             if dest in sources:
                 sources[dest]["Types"].add(matches["type"])
                 sources[dest]["URIs"] = matches["uri"]
diff --git a/apt/files/deb822-migration.sh b/apt/files/deb822-migration.sh
index 10fb7889..7a4fb787 100755
--- a/apt/files/deb822-migration.sh
+++ b/apt/files/deb822-migration.sh
@@ -1,5 +1,11 @@
 #!/bin/sh
 
+##########
+# This script changes all "one-line" APT sources into "deb822" sources.
+# It is responsible for searching and processing the files.
+# The actual format migration is done by a python script.
+##########
+
 deb822_migrate_script=$(command -v deb822-migration.py)
 
 if [ -z "${deb822_migrate_script}" ]; then
@@ -46,4 +52,4 @@ for file in $(find /etc/apt/sources.list.d -mindepth 1 -maxdepth 1 -type f -name
 done
 
 echo "${count} file(s) migrated"
-exit ${rc}
\ No newline at end of file
+exit ${rc}