Table of Contents

Öffentliche API verfolgen und die Kriterien für 1.0

Die öffentliche API der vier Bibliotheken wird jetzt in Dateien verfolgt und bei jedem Build geprüft, und die Bedingungen, unter denen die Version 1.0 werden darf, sind aufgeschrieben. Bis dahin ist die Bibliothek eine Vorschau: Die API darf sich noch ändern, aber nur mit Absicht und sichtbar.

English version: 0028-oeffentliche-api-und-kriterien-fuer-1-0.md

Consequences

  • PublicApiAnalyzers. Microsoft.CodeAnalysis.PublicApiAnalyzers wird von SpatialNET.Core, .Extensions, .Imp und .IO referenziert (Entwicklungsabhängigkeit, nicht Teil der Pakete). Jedes Projekt hat PublicAPI.Shipped.txt (die API der veröffentlichten Versionen) und PublicAPI.Unshipped.txt (die Änderungen seither). Ein öffentlicher Typ oder Member, der in keiner der beiden Dateien steht (RS0016), oder ein aufgeführter, den es nicht mehr gibt (RS0017), lässt den Build scheitern, weil Warnungen Fehler sind. Das fängt eine API-Änderung, die niemand wollte, schon im Pull Request.
  • Zusammen mit der Paketvalidierung. EnablePackageValidation bleibt: Sie vergleicht die gepackte Binärdatei mit dem veröffentlichten Paket und fängt auch Verhalten des Compilers (etwa einen geänderten Standardwert). Die Analyzer vergleichen den Quelltext mit den Dateien im Repository, brauchen kein Netz und zeigen die Änderung im Diff. Die zwei Prüfungen beantworten verschiedene Fragen.
  • Ausgangslage. PublicAPI.Shipped.txt enthält die öffentliche API des Tags v0.4.0-preview.1, gewonnen aus einem git archive des Tags (der Checkout wurde nicht angefasst). Alles seither Hinzugekommene (vorbereitete Distanz, LineMerge, Polygonize, Transformationen, Formen, Bereinigen) steht in PublicAPI.Unshipped.txt.
  • Regeln. RS0016, RS0017 und die übrigen Regeln des Pakets sind Fehler. RS0026 und RS0027 (mehrere Überladungen mit optionalen Parametern) sind in Directory.Build.props abgeschaltet, weil die typisierten Überladungen mit dem gemeinsamen Ende factory = null, gridSize = null Absicht sind (ADR 0012).
  • Arbeiten damit. Eine neue öffentliche API trägt der Code-Fix des Analyzers in der IDE in PublicAPI.Unshipped.txt ein, oder auf der Kommandozeile dotnet format analyzers src/<projekt> --diagnostics RS0016 RS0017 --severity info. Eine Entfernung oder Änderung erscheint als *REMOVED* mit der alten Zeile dahinter. Beim Vorbereiten eines Releases schiebt tools/ship-public-api.ps1 die Einträge aus Unshipped in die Shipped-Dateien (RELEASING.md).
  • Oberflächen-Review (abgeschlossen; das Ergebnis). Die gesamte öffentliche Fläche wurde beim Anlegen der Dateien geprüft, und jeder Befund ist entschieden:
    • Umgesetzt: Hull ist in Shapes aufgegangen. ConvexHull war die einzige Methode ihrer Klasse, während die übrigen Formkonstruktionen in Shapes stehen. Aufrufer nutzen die Erweiterungs-Syntax (geometry.ConvexHull()), die sich nicht ändert; nur ein statischer Aufruf Hull.ConvexHull(geometry) muss zu Shapes.ConvexHull(geometry) werden.
    • Umgesetzt: Die konkreten Klassen von SpatialNET.Imp sind internal. Point, Point3D, PointM, Point3DM, PointSequence, MultiPoint, Path, Ring, Polyline und Polygon hatten kurze, allgemeine Namen, die mit eigenen Typen eines Hosts kollidieren, sobald er SpatialNET.Imp neben seinem Namespace importiert. Öffentlich ist nur ImpGeometryFactory, denn Hosts erreichen die Referenz-Implementierung über die Factory (factory.CreatePoint(...), Wkt.Read(..., factory)); new Point(x, y) wurde nie gebraucht. Die Tests, der Playground und die Benchmarks sehen die Klassen über InternalsVisibleTo.
    • Endgültig: Circle bleibt in SpatialNET.Extensions. Er wird nur von MinimumBoundingCircle geliefert. Er wandert nach SpatialNET.Core, falls Hosts ihn einmal herumreichen müssen, was ohne Bruch möglich ist.
    • Endgültig: die Namen Location/Locations, Validation/ValidationResult, Preparation/PreparedGeometry. Das Muster ist einheitlich: Die Erweiterungsklasse hat einen Namen im Plural oder in der Verlaufsform, der Ergebnistyp einen im Singular. Es steht in der Dokumentation.
    • Endgültig: die Reihenfolge der optionalen Parameter. Simplify(tolerance, preserveTopology, factory, gridSize), Densify(maxSegmentLength, factory) und Buffer(distance, options, factory, gridSize) unterscheiden sich in der Mitte, aber das Ende factory, gridSize ist überall gleich, und das zählt bei Aufrufen mit benannten Argumenten.
    • Endgültig: ValidationResult und ValidationIssue bleiben Records mit öffentlichen Konstruktoren. Ein Host ruft sie nie auf, das Risiko ist klein, und Records ohne öffentlichen Konstruktor sind unbequem.
    • Die zwei Brüche (Hull und die Imp-Klassen) sind vor 1.0 in einer Nebenversion erlaubt. Sie stehen im CHANGELOG, PublicAPI.Unshipped.txt führt sie als *REMOVED*, und CompatibilitySuppressions.xml in SpatialNET.Extensions und SpatialNET.Imp sagt der Paketvalidierung, dass sie gewollt sind; die Dateien entfallen, wenn ein Release die Basis verschiebt.
  • Die Kriterien für 1.0. Die Version 1.0.0 wird veröffentlicht, wenn alles Folgende gilt:
    1. Umfang entschieden. Kein Kandidat für ein Feature ist offen, das die API ändern würde (die Entscheidung, es wegzulassen, zählt); ConcaveHull ist so oder so entschieden.
    2. Oberfläche geprüft. Erledigt: Der Review oben ist abgeschlossen, und jeder Befund ist geändert oder für endgültig erklärt.
    3. Verträge endgültig. Die Interfaces von SpatialNET.Core (IGeometryFactory eingeschlossen) und die Exception-Regeln (ADR 0012) sind das, worauf sich ein Host für die ganze 1.x-Linie verlassen kann. Alles, was noch zu einem Interface hinzukommen könnte, ist schon ein Default-Interface-Member.
    4. Ein echter Host läuft. Mindestens eine echte GIS-Anwendung (gView) nutzt die Bibliothek über ihre eigenen Geometrieklassen und ihre eigene Factory, und ihre Befunde sind behoben.
    5. Qualität ist belegt. Die wöchentlichen Stresstests liefen vier Wochen in Folge grün, die Orakeltests (NTS) sind auf beiden Betriebssystemen grün, und die Benchmarks haben für die wichtigsten Algorithmen eine festgehaltene Basis.
    6. Das Veröffentlichen ist geprobt. Der Release-Workflow hat mindestens zwei Vorabversionen auf nuget.org veröffentlicht, und die Basis der Paketvalidierung ist das vorherige Release.
    7. Dokumentation vollständig. Jeder öffentliche Member hat einen XML-Kommentar, jedes Konzept eine Seite in beiden Sprachen, und der Leitfaden zur Host-Anbindung und die Rezepte laufen gegen die endgültige API.
    8. Keine offenen Vorschau-Hinweise. Der CHANGELOG hat keinen Eintrag, der „Vorschau“, „kann sich ändern“ oder „experimentell“ sagt.
  • Nach 1.0. Semantic Versioning: Kein Bruch in 1.x; eine entfernte oder geänderte API braucht eine neue Hauptversion, der mindestens eine Nebenversion mit [Obsolete] vorausgeht. Neue API kommt mit einer Nebenversion. RELEASING.md und die Paketvalidierung erzwingen die Mechanik schon.
  • Vor 1.0 (jetzt). Eine Nebenversion darf brechen, mit einem Eintrag im CHANGELOG unter „Changed“ oder „Removed“, der das sagt. Eine Patch-Version bricht nie.

Considered Options

  • Nur die Paketvalidierung (verworfen: Sie braucht eine veröffentlichte Basis und das Netz, zeigt Brüche erst beim Packen und nicht die gewollten Ergänzungen)
  • Eine handgeschriebene API-Liste in der Dokumentation (verworfen: Sie driftet; die Analyzer halten die Liste bei jedem Build wahr)
  • RS0026/RS0027 als Warnungen (verworfen: Mit Warnungen als Fehlern lassen sie den Build scheitern; das Muster ist Absicht)
  • Den jetzigen Stand als Beginn von „shipped“ behandeln (verworfen: Das Tag ist die Wahrheit darüber, was Nutzer haben; die späteren Ergänzungen sind unveröffentlicht und gehören in die Unshipped-Datei)
  • Ein festes Datum oder eine feste Version für 1.0 (verworfen: Die Kriterien entscheiden, nicht der Kalender)