From 41940bccc465452e52e7dc9f747681d3dcfa8a42 Mon Sep 17 00:00:00 2001 From: George Barnett Date: Thu, 23 Jan 2025 14:33:28 +0000 Subject: [PATCH] Document what constitutes public API Motivation: SemVer packages should descibe what constitutes their API. Modifications: - Add a doc explaining what the public API is Result: More docs --- .../Documentation.docc/Articles/Public-API.md | 93 +++++++++++++++++++ .../Documentation.docc/Documentation.md | 1 + 2 files changed, 94 insertions(+) create mode 100644 Sources/GRPCCore/Documentation.docc/Articles/Public-API.md diff --git a/Sources/GRPCCore/Documentation.docc/Articles/Public-API.md b/Sources/GRPCCore/Documentation.docc/Articles/Public-API.md new file mode 100644 index 000000000..6da3217ee --- /dev/null +++ b/Sources/GRPCCore/Documentation.docc/Articles/Public-API.md @@ -0,0 +1,93 @@ +# Public API + +Understand what constitutes the public API of gRPC Swift and the commitments +made by the maintainers. + +## Overview + +The gRPC Swift project uses [Semantic Versioning 2.0.0][0] which requires +projects to declare their public API. This document describes what is and isn't +part of the public API; commitments the maintainers make relating to the API; +and guidelines for users. + +For clarity the project is comprised of the following Swift packages: + +- [grpc/grpc-swift][1], +- [grpc/grpc-swift-nio-transport][2], +- [grpc/grpc-swift-protobuf][3], and +- [grpc/grpc-swift-extras][4]. + +## What _is_ and _isn't_ public API + +### Library targets + +All library targets made available as package products as considered to be +public API. Examples of these include `GRPCCore` and `GRPCProtobuf`. + +> Exceptions: +> Targets with names starting with an underscore (`_`) aren't public API. + +### Symbols + +All publicly exposed symbols (i.e. symbols which are declared as `public`) +within public library targets or those which are re-exported from non-public +targets are part of the public API. Examples include `Metadata`, +`ServiceConfig`, and `GRPCServer`. + +> Exceptions: +> - Symbols starting with an underscore (`_`), for example `_someFunction()` and +> `_AnotherType` aren't public API. +> - Initializers where the first character of the first parameter label is an +> underscore, for example `init(_foo:)` aren't public API. + +### Configuration and inputs + +Any configuration, input, and interfaces to executable products which have +inputs (such as command line arguments, or configuration files) are considered +to be public API. Examples of these include the configuration file passed to the +Swift Package Manager build plugin for generating stubs provided by +[grpc-swift-protobuf][3]. + +> Exceptions: +> - Executable _targets_ which aren't exposed as executable _products_. + +## Commitments made by the maintainers + +Without releasing a new major version, the gRPC Swift maintainers commit to not +adding any new types to the global namespace without a "GRPC" prefix. + +To illustrate this, the maintainers may: +1. Add a new type to an existing module called `GRPCPanCakes` but will not add a + new type called `PanCakes` to an existing module. +2. Add a new top-level function to an existing module called `grpcRun()` but + won't add a new top-level function called `run()`. +3. Add a new module called `GRPCFoo`. Any symbols added to the new module at the + point the module becomes API aren't required to have a "GRPC" prefix; symbols + added after that point will be prefixed as required by (1) and (2). + +This allows the project to follow Semantic versioning without breaking adopter +code in minor and patch releases. + +## Guidelines for users + +In order to not have your code broken by a gRPC Swift update you should only use +the public API as described above. There are a number of other guidelines you +should follow as well: + +1. You _may_ conform your own types to protocols provided by gRPC Swift. +2. You _may_ conform types provided by gRPC Swift to your own protocols. +3. You _mustn't_ conform types provided by gRPC Swift to protocols that you + don't own, and you mustn't conform types you don't own to protocols provided + by gRPC Swift. +4. You _may_ extend types provided by gRPC Swift at `package`, `internal`, + `private` or `fileprivate` level. +5. You _may_ extend types provided by gRPC Swift at `public` access level if + doing so means that a symbol clash is impossible (such as including a type + you own in the signature, or prefixing the method with the namespace of your + package in much the same way that gRPC Swift will prefix new symbols). + +[0]: https://semver.org +[1]: https://github.com/grpc/grpc-swift +[2]: https://github.com/grpc/grpc-swift-nio-transport +[3]: https://github.com/grpc/grpc-swift-protobuf +[4]: https://github.com/grpc/grpc-swift-extras diff --git a/Sources/GRPCCore/Documentation.docc/Documentation.md b/Sources/GRPCCore/Documentation.docc/Documentation.md index 8a35bf9d9..b885c72e8 100644 --- a/Sources/GRPCCore/Documentation.docc/Documentation.md +++ b/Sources/GRPCCore/Documentation.docc/Documentation.md @@ -57,6 +57,7 @@ as tutorials. ### Project Information - +- ### Getting involved