Set up release-plz

.github/workflows/create-release-pr.yml

@@ -0,0 +1,35 @@
+name: Create release PR
+
+permissions:
+  pull-requests: write
+  contents: write
+
+on: workflow_dispatch
+
+jobs:
+
+# Create a PR with the new versions and changelog, preparing the next release. When merged to main,
+# the publish-release.yml workflow will automatically publish any Rust package versions.
+create-release-pr:
+    name: Create release PR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    concurrency: # Don't run overlapping instances of this workflow
+      group: release-plz-${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Run release-plz
+        uses: release-plz/[email protected]
+        with:
+          command: release-pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

.github/workflows/publish-release.yml

@@ -0,0 +1,32 @@
+name: Release and unpublished twirp/twirp-build packages
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  # Release any unpublished packages
+  release-plz-release:
+    name: Release-plz release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Run release-plz
+        uses: release-plz/[email protected]
+        with:
+          command: release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

CONTRIBUTING.md

@@ -41,22 +41,15 @@ cargo build && cargo test
 Run clippy and fix any lints:
 
 ```sh
-cargo fmt --all -- --check
-cargo clippy -- --deny warnings -D clippy::unwrap_used
-cargo clippy --tests -- --deny warnings -A clippy::unwrap_used
+make lint
 ```
 
-## Releasing (write access required)
+## Releasing
 
-If you are one of the maintainers of this package then follow this process:
-
-1. Create a PR for this release with following changes:
-  - Updated `CHANGELOG.md` with desired change comments and ensure that it has the version to be released with date at the top.
-  - Go through all recent PRs and make sure they are properly accounted for.
-  - Make sure all changelog entries have links back to their PR(s) if appropriate.
-  - Update package version in Cargo.toml.
-1. Get an approval and merge your PR.
-1. Run ./script/publish from the `main` branch supplying your token and version information.
+1. Go to the `Create Release PR` action and press the button to run the action. This will use `release-plz` to create a new release PR.
+1. Adjust the generated changelog and version number(s) as necessary.
+1. Get PR approval
+1. Merge the PR. The `publish-release.yml` workflow will automatically publish a new release of any crate whose version has changed.
 
 ## Resources
 

Cargo.toml

@@ -1,7 +1,4 @@
 [workspace]
 
-members = [
-    "crates/*",
-    "example",
-]
+members = ["crates/*", "example"]
 resolver = "2"

README.md

@@ -1,113 +1,6 @@
 # twirp-rs
 
-[Twirp is an RPC protocol](https://twitchtv.github.io/twirp/docs/spec_v7.html) based on HTTP and Protocol Buffers (proto). The protocol uses HTTP URLs to specify the RPC endpoints, and sends/receives proto messages as HTTP request/response bodies. Services are defined in a [.proto file](https://developers.google.com/protocol-buffers/docs/proto3), allowing easy implementation of RPC services with auto-generated clients and servers in different languages.
+This repository contains the following crates published to crates.io. Please see their respective README files for more information.
 
-The [canonical implementation](https://github.com/twitchtv/twirp) is in Go, this is a Rust implementation of the protocol. Rust protocol buffer support is provided by the [`prost`](https://github.com/tokio-rs/prost) ecosystem.
-
-Unlike [`prost-twirp`](https://github.com/sourcefrog/prost-twirp), the generated traits for serving and accessing RPCs are implemented atop `async` functions. Because traits containing `async` functions [are not directly supported](https://smallcultfollowing.com/babysteps/blog/2019/10/26/async-fn-in-traits-are-hard/) in Rust versions prior to 1.75, this crate uses the [`async_trait`](https://github.com/dtolnay/async-trait) macro to encapsulate the scaffolding required to make them work.
-
-## Usage
-
-See the [example](./example) for a complete example project.
-
-Define services and messages in a `.proto` file:
-
-```proto
-// service.proto
-package service.haberdash.v1;
-
-service HaberdasherAPI {
-   rpc MakeHat(MakeHatRequest) returns (MakeHatResponse);
-}
-message MakeHatRequest { }
-message MakeHatResponse { }
-```
-
-Add the `twirp-build` crate as a build dependency in your `Cargo.toml` (you'll need `prost-build` too):
-
-```toml
-# Cargo.toml
-[build-dependencies]
-twirp-build = "0.3"
-prost-build = "0.13"
-```
-
-Add a `build.rs` file to your project to compile the protos and generate Rust code:
-
-```rust
-fn main() {
-    let proto_source_files = ["./service.proto"];
-
-    // Tell Cargo to rerun this build script if any of the proto files change
-    for entry in &proto_source_files {
-        println!("cargo:rerun-if-changed={}", entry);
-    }
-
-    prost_build::Config::new()
-        .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]") // enable support for JSON encoding
-        .service_generator(twirp_build::service_generator())
-        .compile_protos(&proto_source_files, &["./"])
-        .expect("error compiling protos");
-}
-```
-
-This generates code that you can find in `target/build/your-project-*/out/example.service.rs`. In order to use this code, you'll need to implement the trait for the proto defined service and wire up the service handlers to a hyper web server. See [the example `main.rs`]( example/src/main.rs) for details.
-
-Include the generated code, create a router, register your service, and then serve those routes in the hyper server:
-
-```rust
-mod haberdash {
-    include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
-}
-
-use axum::Router;
-use haberdash::{MakeHatRequest, MakeHatResponse};
-
-#[tokio::main]
-pub async fn main() {
-    let api_impl = Arc::new(HaberdasherApiServer {});
-    let twirp_routes = Router::new()
-        .nest(haberdash::SERVICE_FQN, haberdash::router(api_impl));
-    let app = Router::new()
-        .nest("/twirp", twirp_routes)
-        .fallback(twirp::server::not_found_handler);
-
-    let tcp_listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
-    if let Err(e) = axum::serve(tcp_listener, app).await {
-        eprintln!("server error: {}", e);
-    }
-}
-
-// Define the server and implement the trait.
-struct HaberdasherApiServer;
-
-#[async_trait]
-impl haberdash::HaberdasherApi for HaberdasherApiServer {
-    async fn make_hat(&self, ctx: twirp::Context, req: MakeHatRequest) -> Result<MakeHatResponse, TwirpErrorResponse> {
-        todo!()
-    }
-}
-```
-
-This code creates an `axum::Router`, then hands it off to `axum::serve()` to handle networking.
-This use of `axum::serve` is optional. After building `app`, you can instead invoke it from any
-`hyper`-based server by importing `twirp::tower::Service` and doing `app.call(request).await`.
-
-## Usage (client side)
-
-On the client side, you also get a generated twirp client (based on the rpc endpoints in your proto). Include the generated code, create a client, and start making rpc calls:
-
-``` rust
-mod haberdash {
-    include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
-}
-
-use haberdash::{HaberdasherApiClient, MakeHatRequest, MakeHatResponse};
-
-#[tokio::main]
-pub async fn main() {
-    let client = Client::from_base_url(Url::parse("http://localhost:3000/twirp/")?)?;
-    let resp = client.make_hat(MakeHatRequest { inches: 1 }).await;
-    eprintln!("{:?}", resp);
-}
-```
+- [`twirp-build`](https://github.com/github/twirp-rs/tree/main/crates/twirp/twirp-build) - A crate for generating twirp client and server interfaces. This is probably what you are looking for.
+- [`twirp`](https://github.com/github/twirp-rs/tree/main/crates/twirp/) - A crate used by code that is generated by `twirp-build`

crates/twirp-build/Cargo.toml

@@ -1,13 +1,18 @@
 [package]
 name = "twirp-build"
 version = "0.7.0"
-authors = ["The blackbird team <[email protected]>"]
 edition = "2021"
 description = "Code generation for async-compatible Twirp RPC interfaces."
 readme = "README.md"
-keywords = ["twirp"]
-categories = ["network-programming"]
+keywords = ["twirp", "prost", "protocol-buffers"]
+categories = [
+    "development-tools::build-utils",
+    "network-programming",
+    "asynchronous",
+]
 repository = "https://github.com/github/twirp-rs"
+license = "MIT"
+license-file = "./LICENSE"
 
 [dependencies]
 prost-build = "0.13"

crates/twirp-build/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crates/twirp-build/README.md

@@ -0,0 +1,113 @@
+# `twirp-build`
+
+[Twirp is an RPC protocol](https://twitchtv.github.io/twirp/docs/spec_v7.html) based on HTTP and Protocol Buffers (proto). The protocol uses HTTP URLs to specify the RPC endpoints, and sends/receives proto messages as HTTP request/response bodies. Services are defined in a [.proto file](https://developers.google.com/protocol-buffers/docs/proto3), allowing easy implementation of RPC services with auto-generated clients and servers in different languages.
+
+The [canonical implementation](https://github.com/twitchtv/twirp) is in Go, this is a Rust implementation of the protocol. Rust protocol buffer support is provided by the [`prost`](https://github.com/tokio-rs/prost) ecosystem.
+
+Unlike [`prost-twirp`](https://github.com/sourcefrog/prost-twirp), the generated traits for serving and accessing RPCs are implemented atop `async` functions. Because traits containing `async` functions [are not directly supported](https://smallcultfollowing.com/babysteps/blog/2019/10/26/async-fn-in-traits-are-hard/) in Rust versions prior to 1.75, this crate uses the [`async_trait`](https://github.com/dtolnay/async-trait) macro to encapsulate the scaffolding required to make them work.
+
+## Usage
+
+See the [example](./example) for a complete example project.
+
+Define services and messages in a `.proto` file:
+
+```proto
+// service.proto
+package service.haberdash.v1;
+
+service HaberdasherAPI {
+   rpc MakeHat(MakeHatRequest) returns (MakeHatResponse);
+}
+message MakeHatRequest { }
+message MakeHatResponse { }
+```
+
+Add the `twirp-build` crate as a build dependency in your `Cargo.toml` (you'll need `prost-build` too):
+
+```toml
+# Cargo.toml
+[build-dependencies]
+twirp-build = "0.3"
+prost-build = "0.13"
+```
+
+Add a `build.rs` file to your project to compile the protos and generate Rust code:
+
+```rust
+fn main() {
+    let proto_source_files = ["./service.proto"];
+
+    // Tell Cargo to rerun this build script if any of the proto files change
+    for entry in &proto_source_files {
+        println!("cargo:rerun-if-changed={}", entry);
+    }
+
+    prost_build::Config::new()
+        .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]") // enable support for JSON encoding
+        .service_generator(twirp_build::service_generator())
+        .compile_protos(&proto_source_files, &["./"])
+        .expect("error compiling protos");
+}
+```
+
+This generates code that you can find in `target/build/your-project-*/out/example.service.rs`. In order to use this code, you'll need to implement the trait for the proto defined service and wire up the service handlers to a hyper web server. See [the example `main.rs`]( example/src/main.rs) for details.
+
+Include the generated code, create a router, register your service, and then serve those routes in the hyper server:
+
+```rust
+mod haberdash {
+    include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
+}
+
+use axum::Router;
+use haberdash::{MakeHatRequest, MakeHatResponse};
+
+#[tokio::main]
+pub async fn main() {
+    let api_impl = Arc::new(HaberdasherApiServer {});
+    let twirp_routes = Router::new()
+        .nest(haberdash::SERVICE_FQN, haberdash::router(api_impl));
+    let app = Router::new()
+        .nest("/twirp", twirp_routes)
+        .fallback(twirp::server::not_found_handler);
+
+    let tcp_listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
+    if let Err(e) = axum::serve(tcp_listener, app).await {
+        eprintln!("server error: {}", e);
+    }
+}
+
+// Define the server and implement the trait.
+struct HaberdasherApiServer;
+
+#[async_trait]
+impl haberdash::HaberdasherApi for HaberdasherApiServer {
+    async fn make_hat(&self, ctx: twirp::Context, req: MakeHatRequest) -> Result<MakeHatResponse, TwirpErrorResponse> {
+        todo!()
+    }
+}
+```
+
+This code creates an `axum::Router`, then hands it off to `axum::serve()` to handle networking.
+This use of `axum::serve` is optional. After building `app`, you can instead invoke it from any
+`hyper`-based server by importing `twirp::tower::Service` and doing `app.call(request).await`.
+
+## Usage (client side)
+
+On the client side, you also get a generated twirp client (based on the rpc endpoints in your proto). Include the generated code, create a client, and start making rpc calls:
+
+``` rust
+mod haberdash {
+    include!(concat!(env!("OUT_DIR"), "/service.haberdash.v1.rs"));
+}
+
+use haberdash::{HaberdasherApiClient, MakeHatRequest, MakeHatResponse};
+
+#[tokio::main]
+pub async fn main() {
+    let client = Client::from_base_url(Url::parse("http://localhost:3000/twirp/")?)?;
+    let resp = client.make_hat(MakeHatRequest { inches: 1 }).await;
+    eprintln!("{:?}", resp);
+}
+```