Ö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.PublicApiAnalyzerswird vonSpatialNET.Core,.Extensions,.Impund.IOreferenziert (Entwicklungsabhängigkeit, nicht Teil der Pakete). Jedes Projekt hatPublicAPI.Shipped.txt(die API der veröffentlichten Versionen) undPublicAPI.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.
EnablePackageValidationbleibt: 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.txtenthält die öffentliche API des Tagsv0.4.0-preview.1, gewonnen aus einemgit archivedes Tags (der Checkout wurde nicht angefasst). Alles seither Hinzugekommene (vorbereitete Distanz,LineMerge,Polygonize, Transformationen, Formen, Bereinigen) steht inPublicAPI.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.propsabgeschaltet, weil die typisierten Überladungen mit dem gemeinsamen Endefactory = null, gridSize = nullAbsicht sind (ADR 0012). - Arbeiten damit. Eine neue öffentliche API trägt der Code-Fix des Analyzers in der IDE in
PublicAPI.Unshipped.txtein, oder auf der Kommandozeiledotnet 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 schiebttools/ship-public-api.ps1die 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:
Hullist inShapesaufgegangen.ConvexHullwar die einzige Methode ihrer Klasse, während die übrigen Formkonstruktionen inShapesstehen. Aufrufer nutzen die Erweiterungs-Syntax (geometry.ConvexHull()), die sich nicht ändert; nur ein statischer AufrufHull.ConvexHull(geometry)muss zuShapes.ConvexHull(geometry)werden. - Umgesetzt: Die konkreten Klassen von
SpatialNET.Impsindinternal.Point,Point3D,PointM,Point3DM,PointSequence,MultiPoint,Path,Ring,PolylineundPolygonhatten kurze, allgemeine Namen, die mit eigenen Typen eines Hosts kollidieren, sobald erSpatialNET.Impneben seinem Namespace importiert. Öffentlich ist nurImpGeometryFactory, 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 überInternalsVisibleTo. - Endgültig:
Circlebleibt inSpatialNET.Extensions. Er wird nur vonMinimumBoundingCirclegeliefert. Er wandert nachSpatialNET.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)undBuffer(distance, options, factory, gridSize)unterscheiden sich in der Mitte, aber das Endefactory, gridSizeist überall gleich, und das zählt bei Aufrufen mit benannten Argumenten. - Endgültig:
ValidationResultundValidationIssuebleiben 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 (
Hullund dieImp-Klassen) sind vor 1.0 in einer Nebenversion erlaubt. Sie stehen im CHANGELOG,PublicAPI.Unshipped.txtführt sie als*REMOVED*, undCompatibilitySuppressions.xmlinSpatialNET.ExtensionsundSpatialNET.Impsagt der Paketvalidierung, dass sie gewollt sind; die Dateien entfallen, wenn ein Release die Basis verschiebt.
- Umgesetzt:
- Die Kriterien für 1.0. Die Version 1.0.0 wird veröffentlicht, wenn alles Folgende gilt:
- Umfang entschieden. Kein Kandidat für ein Feature ist offen, das die API ändern würde (die Entscheidung, es wegzulassen, zählt);
ConcaveHullist so oder so entschieden. - Oberfläche geprüft. Erledigt: Der Review oben ist abgeschlossen, und jeder Befund ist geändert oder für endgültig erklärt.
- Verträge endgültig. Die Interfaces von
SpatialNET.Core(IGeometryFactoryeingeschlossen) 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. - 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.
- 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.
- 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.
- 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.
- Keine offenen Vorschau-Hinweise. Der CHANGELOG hat keinen Eintrag, der „Vorschau“, „kann sich ändern“ oder „experimentell“ sagt.
- Umfang entschieden. Kein Kandidat für ein Feature ist offen, das die API ändern würde (die Entscheidung, es wegzulassen, zählt);
- 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)