Public API tracking and the criteria for 1.0
The public API of the four libraries is now tracked in files and checked on every build, and the conditions under which the version may become 1.0 are written down. Until then the library is a preview: the API may still change, but only on purpose and visibly.
German version: 0028-oeffentliche-api-und-kriterien-fuer-1-0.de.md
Consequences
- PublicApiAnalyzers.
Microsoft.CodeAnalysis.PublicApiAnalyzersis referenced bySpatialNET.Core,.Extensions,.Impand.IO(development dependency, not part of the packages). Each project hasPublicAPI.Shipped.txt(the API of the released versions) andPublicAPI.Unshipped.txt(the changes since). A public type or member that is in neither file (RS0016), or a listed one that no longer exists (RS0017), fails the build, because warnings are errors. This catches an API change that nobody meant, in the pull request. - Together with the package validation.
EnablePackageValidationstays: it compares the packed binary with the published package and also catches behaviour of the compiler (for example a changed default value). The analyzers compare the source with the files in the repository, need no network, and show the change in the diff. The two checks answer different questions. - Starting point.
PublicAPI.Shipped.txtholds the public API of the tagv0.4.0-preview.1, taken from agit archiveof the tag (the checkout was not touched). Everything added since (prepared distance,LineMerge,Polygonize, transformations, shapes, clean-up) is inPublicAPI.Unshipped.txt. - Rules. RS0016 and RS0017 and the other rules of the package are errors. RS0026 and RS0027 (several overloads with optional parameters) are switched off in
Directory.Build.props, because the typed overloads with the shared tailfactory = null, gridSize = nullare intended (ADR 0012). - Working with it. A new public API is added to
PublicAPI.Unshipped.txtby the code fix of the analyzer in the IDE, or on the command line withdotnet format analyzers src/<project> --diagnostics RS0016 RS0017 --severity info. A removal or change appears as*REMOVED*followed by the old line. When a release is prepared,tools/ship-public-api.ps1moves the unshipped entries into the shipped files (RELEASING.md). - Surface review (done; the result). The whole public surface was reviewed when the files were written, and each finding was decided:
- Done:
Hullis merged intoShapes.ConvexHullwas the only method of its class while the other shape constructions are inShapes. Callers use the extension syntax (geometry.ConvexHull()), which is unchanged; only a static callHull.ConvexHull(geometry)has to becomeShapes.ConvexHull(geometry). - Done: the concrete classes of
SpatialNET.Impareinternal.Point,Point3D,PointM,Point3DM,PointSequence,MultiPoint,Path,Ring,PolylineandPolygonhad short, generic names that clash with a host's own types as soon as it importsSpatialNET.Impnext to its namespace. OnlyImpGeometryFactoryis public, because hosts reach the reference implementation through the factory (factory.CreatePoint(...),Wkt.Read(..., factory));new Point(x, y)was never needed. The tests, the playground and the benchmarks see the classes throughInternalsVisibleTo. - Final:
Circlestays inSpatialNET.Extensions. It is only returned byMinimumBoundingCircle. It moves toSpatialNET.Coreif hosts ever need to pass it around, which is possible without a break. - Final: the names
Location/Locations,Validation/ValidationResult,Preparation/PreparedGeometry. The pattern is consistent: the extension class has a plural or gerund name, the result type a singular one. It is described in the documentation. - Final: the order of optional parameters.
Simplify(tolerance, preserveTopology, factory, gridSize),Densify(maxSegmentLength, factory)andBuffer(distance, options, factory, gridSize)differ in the middle, but the tailfactory, gridSizeis the same everywhere, which is what matters for calls with named arguments. - Final:
ValidationResultandValidationIssuestay records with public constructors. A host never calls them, the risk is small, and records without a public constructor are inconvenient. - The two breaking changes (
Hulland theImpclasses) are allowed before 1.0 in a minor version. They are in the CHANGELOG,PublicAPI.Unshipped.txtlists them as*REMOVED*, andCompatibilitySuppressions.xmlinSpatialNET.ExtensionsandSpatialNET.Imptells the package validation that they are intended; the files go away when a release moves the baseline.
- Done:
- The criteria for 1.0. The version 1.0.0 is released when all of these hold:
- Scope decided. No candidate feature is left open that would change the API (a decision to leave it out counts);
ConcaveHullis decided one way or the other. - Surface reviewed. Done: the review above is complete, and every finding is changed or declared final.
- Contracts final. The interfaces of
SpatialNET.Core(IGeometryFactoryincluded) and the exception rules (ADR 0012) are what a host can rely on for the whole 1.x line. Anything that might still be added to an interface is already a default interface member. - A real host works. At least one real GIS application (gView) uses the library through its own geometry classes and its own factory, and its findings are fixed.
- Quality is shown. The weekly stress tests have run green for four weeks in a row, the oracle tests (NTS) are green on both operating systems, and the benchmarks have a recorded baseline for the main algorithms.
- Releasing is rehearsed. The release workflow has published at least two pre-releases to nuget.org, and the package validation baseline is the previous release.
- Documentation is complete. Every public member has an XML comment, every concept has a page in both languages, and the host integration guide and the cookbook run against the final API.
- No open preview notes. The CHANGELOG has no entry that says "preview", "may change" or "experimental".
- Scope decided. No candidate feature is left open that would change the API (a decision to leave it out counts);
- After 1.0. Semantic Versioning: no breaking change in 1.x; a removed or changed API needs a new major version, preceded by
[Obsolete]for at least one minor version. New API is added with a minor version. RELEASING.md and the package validation already enforce the mechanics. - Before 1.0 (now). A minor version may break, with an entry in the CHANGELOG under "Changed" or "Removed" that says so. A patch version never breaks.
Considered Options
- Package validation alone (rejected: it needs a published baseline and the network, shows breaks only when packing, and not the intended additions)
- A hand-written API list in the documentation (rejected: it drifts; the analyzers keep the list true on every build)
- RS0026/RS0027 as warnings (rejected: with warnings as errors they fail the build; the pattern is intended)
- Treating the current state as the start of "shipped" (rejected: the tag is the truth about what users have; the later additions are unreleased and belong in the unshipped file)
- A fixed date or version for 1.0 (rejected: the criteria decide, not the calendar)