feat(docs): Changelog mit "was ist seit meiner Fassung neu"

Bisher musste ein Agent, der eine Anbindung aktualisiert, die gesamte Historie lesen - oder er las gar nichts und uebersah eine brechende Aenderung. Beides schlecht. - public/docs/changelog.json ist die einzige Quelle. Je Fassung eine Zusammenfassung, je Aenderung Bereich, ein "breaking"-Kennzeichen und vor allem ein Feld "action" mit dem, was konkret zu tun ist. Steht dort null, ist nichts zu tun - das ist die haeufigste und nuetzlichste Antwort. - GET /api/updateservice/v1/changelog?since=2.2.0 liefert nur die neueren Fassungen, dazu die Anzahl der Punkte mit Handlungsbedarf und der brechenden Aenderungen. count:0 heisst "du bist auf Stand" - dann muss gar nichts gelesen werden. Optional nach Bereich filterbar (?area=packager). - /docs/changelog.php rendert dieselbe Datei fuer Menschen, mit Eingabefeld fuer die eigene Fassung. Bewusst dieselbe Quelle: zwei Fassungen zu pflegen hiesse, sie auseinanderlaufen zu lassen. - DeploymentcenterSdk.Version im SDK ist der Bezugspunkt. Damit muss die Fassung nicht abgetippt werden. - AGENT_PROMPT_TEMPLATE.md verpflichtet dazu, sie in der AGENTS.md des Projekts festzuhalten und vor jeder Aenderung an der Anbindung den Unterschied abzufragen. Auch in der Kurzfassung fuer knappe Prompt-Budgets. Die Historie ist rueckwirkend bis 2.0.0 gefuellt: 6 Fassungen, 25 Punkte mit Handlungsbedarf, 13 brechende Aenderungen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 16:45:50 +02:00
parent 1967b49ad7
commit a8b9f6f7c9
7 changed files with 657 additions and 1 deletions
@@ -0,0 +1,58 @@
+using System;
+
+namespace Deploymentcenter.Client
+{
+    /// <summary>
+    /// Auskunft ueber die eingebundene SDK-Fassung.
+    ///
+    /// Wozu das gut ist: Wer eine Anbindung aktualisiert, will nicht die
+    /// gesamte Historie lesen, sondern nur wissen, was sich seit der eigenen
+    /// Fassung geaendert hat. Dafuer muss die Anwendung festhalten, gegen
+    /// welche Fassung sie gebaut wurde - und genau das ist
+    /// <see cref="Version"/>.
+    ///
+    /// Der Wert wandert automatisch in die Update-Pruefung und den Heartbeat,
+    /// sodass im Deploymentcenter sichtbar wird, welche Installation auf
+    /// welchem Stand haengt. Ohne diese Angabe bliebe nur Nachfragen.
+    ///
+    /// Abfragen laesst sich der Unterschied so:
+    ///
+    ///     GET /api/updateservice/v1/changelog?since=2.2.0
+    ///
+    /// Die Antwort nennt nur die neueren Fassungen, dazu die Anzahl der
+    /// Punkte mit Handlungsbedarf und der brechenden Aenderungen.
+    /// </summary>
+    public static class DeploymentcenterSdk
+    {
+        /// <summary>
+        /// Fassung dieses SDK. Bei jeder Auslieferung mitzufuehren - sie ist
+        /// der Bezugspunkt fuer den Changelog.
+        /// </summary>
+        public const string Version = "2.5.0";
+
+        /// <summary>
+        /// Adresse, unter der sich der Unterschied zur eigenen Fassung
+        /// abfragen laesst.
+        /// </summary>
+        public static string ChangelogUrl(string baseUrl, string? since = null)
+        {
+            string clean = (baseUrl ?? string.Empty).TrimEnd('/');
+            string url = clean + "/api/updateservice/v1/changelog";
+
+            string from = string.IsNullOrWhiteSpace(since) ? Version : since!;
+            return url + "?since=" + Uri.EscapeDataString(from);
+        }
+
+        /// <summary>
+        /// Kurzer Vermerk fuer Protokolle und Fehlerberichte. Taucht ein
+        /// Problem auf, ist damit sofort ersichtlich, gegen welche Fassung die
+        /// Anbindung gebaut wurde.
+        /// </summary>
+        public static string Describe(string? appVersion = null)
+        {
+            return string.IsNullOrWhiteSpace(appVersion)
+                ? $"Deploymentcenter-SDK {Version}"
+                : $"{appVersion} (Deploymentcenter-SDK {Version})";
+        }
+    }
+}