From 55eee22091f6bb895ac1007c24b5b3a684675993 Mon Sep 17 00:00:00 2001 From: Adam Liddell Date: Fri, 19 Jul 2019 13:23:00 +0000 Subject: [PATCH] Add migration docs --- README.md | 23 +++++++--- {.github => docs}/CONTRIBUTING.md | 0 docs/MIGRATION.md | 71 +++++++++++++++++++++++++++++++ tools/rulegen/README.footer.md | 16 +++++-- tools/rulegen/README.header.md | 1 + 5 files changed, 100 insertions(+), 11 deletions(-) rename {.github => docs}/CONTRIBUTING.md (100%) create mode 100644 docs/MIGRATION.md diff --git a/README.md b/README.md index 8df06bed1..a9237d87f 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ - [Scala](/scala/README.md) - [Swift](/swift/README.md) - [Example Usage](#example-usage) +- [Migration](#migration) - [Developers](#developers) - [Code Layout](#code-layout) - [Rule Generation](#rule-generation) @@ -91,9 +92,9 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "rules_proto_grpc", - urls = ["https://github.com/rules-proto-grpc/rules_proto_grpc/archive/2b2f15b81a2913ef1283ec85cda4e52481081c2a.tar.gz"], - sha256 = "dfd757ebd9d65218ea3a45ed2f782d71e183c83e7cb2babd2e46657e75b28bbe", - strip_prefix = "rules_proto_grpc-2b2f15b81a2913ef1283ec85cda4e52481081c2a", + urls = ["https://github.com/rules-proto-grpc/rules_proto_grpc/archive/b08d568056410a3bb290c004005afb420452d5f8.tar.gz"], + sha256 = "8367b214d51767403b70d072531ca93c88de735f9290e0208ed9fba1116de9ae", + strip_prefix = "rules_proto_grpc-b08d568056410a3bb290c004005afb420452d5f8", ) load("@rules_proto_grpc//:repositories.bzl", "rules_proto_grpc_toolchains") @@ -293,6 +294,12 @@ access that rule by adding `_pb` at the end of the rule name, like `bazel build //example/proto:cpp_thing_proto_pb`. +## Migration + +For users migrating from the [stackb/rules_proto](https://github.com/stackb/rules_proto) +rules, please see the help at [MIGRATION.md](/docs/MIGRATION.md) + + ## Developers ### Code Layout @@ -346,11 +353,12 @@ Briefly, here's how the rules work: 1. Using the `proto_library` graph, an aspect walks through the [`ProtoInfo`](https://docs.bazel.build/versions/master/skylark/lib/ProtoInfo.html) providers on the `deps` attribute to `{lang}_{proto|grpc}_compile`. This - finds all the directly and transitively required proto files., along with + finds all the directly and transitively required proto files, along with their options. 2. At each node visited by the aspect, `protoc` is invoked with the relevant - plugins and options to generate the desired outputs. + plugins and options to generate the desired outputs. The aspect uses only + the generated proto descriptors from the `ProtoInfo` providers. 3. Once the aspect stage is complete, all generated outputs are optionally gathered into a final output tree. @@ -438,10 +446,11 @@ def example_compile(**kwargs): This project is derived from [stackb/rules_proto](https://github.com/stackb/rules_proto) under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) license and -this project therefore maintains the terms of that license. +this project therefore maintains the terms of that license. An overview of the +changes can be found at [MIGRATION.md](/docs/MIGRATION.md). ## Contributing -Contributions are very welcome. Please see [CONTRIBUTING](/.github/CONTRIBUTING.md) +Contributions are very welcome. Please see [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for further details. diff --git a/.github/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 000000000..6b1f7cd31 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,71 @@ +# Migration + +For users migrating from the [stackb/rules_proto](https://github.com/stackb/rules_proto) +rules, please see the following sections for general and language-specific +changes that you may need to make to adopt these rules. If you are just an +end-user of the rules, it is mostly minor changes to how the rules are loaded, +for which the language-specific rules pages will get you up to speed. + +If you need help migrating an existing rule-set, please open an Issue and we'll +help where possible. + + +## General + +- All languages are now compiled by the aspect-based compilation described in + [How-it-works](#how-it-works). Due to constraints on Bazel aspects, this + means the `plugin_options` attribute on rules is no longer supportable; + although this attribute is still supported at the plugin level +- The layout of `.bzl` files to `load()` has been changed. Rules are now in + `//{lang}:defs.bzl` and workspace rules are in `//{lang}:repositories.bzl`. + The old paths are still supported, but may be removed in a future release +- The names of the language plugins have been updated from `{lang}` to + `{lang}_plugin` +- Support has been added for plugins that have non-predictable output file + layouts by using `ctx.actions.declare_directory` +- Common functions have moved into `.bzl` files in `/internal` +- The previous transitive based compilation method is no longer available +- Dependencies have been updated +- The `protoc` compiler is now resolved via a toolchain, requiring users to + register the toolchain with `rules_proto_grpc_toolchains`. This is shown in + the `WORKSPACE` example in the documentation +- Test workspaces have been added to ensure the rules produce the correct + outputs for a selection of known issues +- The use of `--incompatible-*` flags is no longer required + + +## Language Specific + +### Dart + +- Dart is presently no longer supported, due to lack of maintenance of the + upstream rules + +### Go + +- Due to restrictions on attributes sent to a Bazel aspect, the `importmap` + attribute is no longer supported. If you need this behaviour, you may need to + re-define your own plugin for the Go protoc plugin + + +### Node.js + +- The Node.js rules have moved to the standard `bazel_build_rules_nodejs` as + the upstream provider of rules +- The Node.js rules have moved from `/node` to `/nodejs` + + +### Python + +- Python dependencies have been updated. The `protobuf` package is now pulled + directly from the `@com_google_protobuf` repo rather than via Pip +- The requirements files have been merged and moved to + `//python:requirements.txt` +- Support for [grpclib](https://github.com/vmagamedov/grpclib) has been added as + an asyncio gRPC implementation + + +### Rust + +- Rust raze dependencies are now internally managed due to outdated versions + upstream. diff --git a/tools/rulegen/README.footer.md b/tools/rulegen/README.footer.md index ae2068f4f..ba8ffece7 100644 --- a/tools/rulegen/README.footer.md +++ b/tools/rulegen/README.footer.md @@ -107,6 +107,12 @@ access that rule by adding `_pb` at the end of the rule name, like `bazel build //example/proto:cpp_thing_proto_pb`. +## Migration + +For users migrating from the [stackb/rules_proto](https://github.com/stackb/rules_proto) +rules, please see the help at [MIGRATION.md](/docs/MIGRATION.md) + + ## Developers ### Code Layout @@ -160,11 +166,12 @@ Briefly, here's how the rules work: 1. Using the `proto_library` graph, an aspect walks through the [`ProtoInfo`](https://docs.bazel.build/versions/master/skylark/lib/ProtoInfo.html) providers on the `deps` attribute to `{lang}_{proto|grpc}_compile`. This - finds all the directly and transitively required proto files., along with + finds all the directly and transitively required proto files, along with their options. 2. At each node visited by the aspect, `protoc` is invoked with the relevant - plugins and options to generate the desired outputs. + plugins and options to generate the desired outputs. The aspect uses only + the generated proto descriptors from the `ProtoInfo` providers. 3. Once the aspect stage is complete, all generated outputs are optionally gathered into a final output tree. @@ -252,10 +259,11 @@ def example_compile(**kwargs): This project is derived from [stackb/rules_proto](https://github.com/stackb/rules_proto) under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) license and -this project therefore maintains the terms of that license. +this project therefore maintains the terms of that license. An overview of the +changes can be found at [MIGRATION.md](/docs/MIGRATION.md). ## Contributing -Contributions are very welcome. Please see [CONTRIBUTING](/.github/CONTRIBUTING.md) +Contributions are very welcome. Please see [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for further details. diff --git a/tools/rulegen/README.header.md b/tools/rulegen/README.header.md index 60d39f28d..2065a2d26 100644 --- a/tools/rulegen/README.header.md +++ b/tools/rulegen/README.header.md @@ -34,6 +34,7 @@ - [Scala](/scala/README.md) - [Swift](/swift/README.md) - [Example Usage](#example-usage) +- [Migration](#migration) - [Developers](#developers) - [Code Layout](#code-layout) - [Rule Generation](#rule-generation)