Adds Protobuf Editions for Schema Producers to the GitHub code repository.

PiperOrigin-RevId: 563110832

docs/design/editions/README.md

@@ -23,4 +23,5 @@ The following topics are in this repository:
 *   [Life of an Edition](life-of-an-edition.md)
 *   [Protobuf Editions Design: Features](protobuf-editions-design-features.md)
 *   [Editions: Life of a Featureset](editions-life-of-a-featureset.md)
+*   [Protobuf Editions for Schema Producers](protobuf-editions-for-schema-producers.md)
 *   [Edition Naming](edition-naming.md)

docs/design/editions/protobuf-editions-for-schema-producers.md

@@ -0,0 +1,127 @@
+### Protobuf Editions for Schema Producers
+
+**Author:** [@fowles](https://github.com/fowles)
+
+Explains the expected use of and interaction with editions for schema providers
+and their customers.
+
+## Background
+
+The [Protobuf Editions](what-are-protobuf-editions.md) project uses "editions"
+to allow Protobuf to safely evolve over time. This is primarily accomplished
+through ["features"](protobuf-editions-design-features.md). The first edition
+(colloquially known as "Edition Zero") will use features to unify proto2 and
+proto3 ([Edition Zero Features](edition-zero-features.md)). This document will
+use definitions from [Protobuf Editions: Rollout](protobuf-editions-rollout.md)
+but focus primarily on the use case of **Schema Producers** and **Schema
+Consumers**:
+
+> **Schema Producers** are teams that produce `.proto` files for the consumption
+> of other teams.
+
+As a reminder, features will generally not change the wire format of messages
+and thus changing the edition for a `.proto` will not change the wire format of
+message.
+
+## Initial Release
+
+There will be a large period of time during which `protoc` is able to consume
+`proto3`, `proto2`, and editions files. Once all of the supported `protoc`
+releases handle editions, schema producers should upgrade their published
+`.proto` files to edition zero. The protobuf team will provide a tool that
+upgrades `proto2` and `proto3` files to edition zero in a fully compatible way.
+
+### Edition Zero Features
+
+In order to unify proto2 and proto3, "Edition Zero" is taking an opinionated
+stance on which choices are good and bad, by choosing "good" defaults and
+requiring explicit requests for the "bad" semantics
+([Edition Zero Features](edition-zero-features.md)). Schema producers that are
+simply upgrading existing `.proto` files should publish these files as produced
+by the upgrade tool. This will ensure wire compatibility. Newly published
+`.proto` files should use the default values from this first edition.
+
+## Steady State Flow
+
+For the most part, editions should not disturb the general pattern for schema
+producers. Any schema producer should already specify what versions of protobuf
+they support and should not support versions of protobuf that are themselves
+unsupported. Schema producers should generally publish all of their `.proto`
+files with a consistent edition for the simplicity of their users. When updating
+the edition for their `.proto` files, producers should target an edition
+supported by all of the versions of protobuf in their support matrix. **A good
+rule of thumb is to target the newest edition supported by the oldest release of
+protobuf in the support matrix.**
+
+### Best Practices
+
+#### Publish `.proto` files
+
+Schema producers should publish `.proto` files and not generated sources. This
+is already the case and editions do not change it. Publishing generated sources
+can lead to mismatches between the compiler and runtime environment used.
+Protobuf does not support mixed generation/runtime configurations and sometimes
+security patches require updating both.
+
+#### Minimize use of features
+
+Codegenerator specific [features](protobuf-editions-design-features.md) (like
+`features.(pb.cpp).string_field_type`) should only be applied within the context
+of a single code base. **Consumers** of published schemas may wish to add
+generator specific features (either by hand or with an automated `.proto`
+refactoring tool), but **producers** should not force that onto users.
+
+## Client Usage Patterns
+
+Consumers’ usage is heavily constrained by their build system. Language agnostic
+build systems, like Bazel, can run `protoc` as one of the build steps. Language
+specific build systems, like Maven or Go, make running `protoc` more difficult
+and so consumers often avoid it. Languages like Python that traditionally lack a
+build system are more extreme.
+
+### Running `protoc` Directly
+
+Because language-specific features will not change the wire format of messages,
+clients will be able to update to newer editions or specify specific features
+appropriate to their environment while still connecting to external endpoints.
+
+In particular, protobuf will provide two distinct mechanisms for supporting
+these users. First, we will provide tools for automating updates to `.proto`
+files in a safe way. These tools will apply semantic patches to `.proto` files
+that they can then commit into source control. Second, we will provide
+primitives in `protoc` to compile a `.proto` file and a semantic patch as a set
+of inputs so that users never have to materialize the modified `.proto` file.
+Protobuf team will investigate adding support for semantic patches when it
+addresses Bazel rules.
+
+In the long term, we want a Bazel rule (and possibly similar for other build
+systems) that seamlessly packages changes like:
+
+```proto
+proto_library(
+    name = "cloud_spanner_proto",
+    modifications = ["cloud_spanner.change_spec"],
+    deps = ["@com_google_cloud//spanner"],
+)
+```
+
+### Publishing Generated Libraries
+
+As a reminder, publishing generated code is not a good idea. It frequently runs
+afoul of runtime/generation time mismatches and is an active source of confusion
+where users are unable to reason about what version they are on.
+
+Teams determined to do this anyway should adhere to the following best
+practices.
+
+*   Publish generated libraries using semver.
+*   Publish both the generated code and the protobuf runtime.
+*   Pin the protobuf runtime library to the exact version used to generate the
+    library.
+*   When upgrading the `protoc` generator for a major, minor, or micro release,
+    increment the corresponding number in the published library’s version.
+*   When updating the edition of the `.proto` file, increment the major number
+    of the published library’s version.
+
+It is worth note that only the last bullet point is new, everything else is a
+restatement of current best practice.