docs: update documentation to use buf.gen.yaml v2 (#162)

The Buf CLI 1.32.0 introduced a v2 config format for buf.gen.yaml ([blog post](https://buf.build/blog/buf-cli-next-generation)). This PR updates the examples in documentation to use buf.gen.yaml v2 for generating code. --------- Signed-off-by: hirasawayuki <[email protected]> Signed-off-by: Nick Snyder <[email protected]> Signed-off-by: Philip K. Warren <[email protected]> Co-authored-by: Nick Snyder <[email protected]> Co-authored-by: Philip K. Warren <[email protected]> Signed-off-by: Steve Ayers <[email protected]>
connectrpc · Sep 30, 2024 · 4cf2d9c · 4cf2d9c
1 parent a3b2c53
commit 4cf2d9c
Show file tree

Hide file tree

Showing 9 changed files with 176 additions and 142 deletions.
diff --git a/docs/go/getting-started.md b/docs/go/getting-started.md
@@ -89,17 +89,17 @@ configuration files to get going. (If you'd prefer, you can skip this section
 and use `protoc` instead &mdash; `protoc-gen-connect-go` behaves like any other
 plugin.)
 
-First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf mod init`. Next,
+First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf config init`. Next,
 tell Buf how to generate code by putting this into
 [`buf.gen.yaml`][buf.gen.yaml]:
 
 ```yaml
-version: v1
+version: v2
 plugins:
-  - plugin: go
+  - local: protoc-gen-go
     out: gen
     opt: paths=source_relative
-  - plugin: connect-go
+  - local: protoc-gen-connect-go
     out: gen
     opt: paths=source_relative
 ```
@@ -333,8 +333,8 @@ query parameters. More importantly, your users got an idiomatic, type-safe
 client without *any* extra work on your part.
 
 [buf]: https://buf.build/
-[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml
-[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml
+[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml
+[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml
 [buf-cli]: https://github.com/bufbuild/buf
 [cURL]: https://curl.se/
 [godoc]: https://pkg.go.dev/connectrpc.com/connect

diff --git a/docs/kotlin/generating-code.md b/docs/kotlin/generating-code.md
@@ -64,19 +64,19 @@ When developing a new project, 2 new files need to be created:
 The first file, `buf.yaml`, can be created by running:
 
 ```bash
-buf mod init
+buf config init
 ```
 
 The second file, `buf.gen.yaml`, needs to be created manually and specifies
 which plugins should be used to generate code. An example of this
 file is shown below:
 
 ```yaml
-version: v1
+version: v2
 plugins:
-  - plugin: buf.build/connectrpc/kotlin
+  - remote: buf.build/connectrpc/kotlin
     out: generated
-  - plugin: buf.build/protocolbuffers/java
+  - remote: buf.build/protocolbuffers/java
     out: generated
 ```
 
@@ -156,8 +156,8 @@ The following generation options can be combined in the `opt` field of the `buf.
 
 [available-plugins]: https://buf.build/plugins
 [buf]: https://buf.build/docs/
-[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml
-[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml
+[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml
+[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml
 [buf-cli]: https://buf.build/docs/installation
 [connect-kotlin]: https://github.com/connectrpc/connect-kotlin
 [connect-kotlin-plugin]: https://buf.build/connectrpc/kotlin

diff --git a/docs/kotlin/getting-started.md b/docs/kotlin/getting-started.md
@@ -50,38 +50,32 @@ is not overridden, the rest of the example will need to replace `com.example.eli
 Create an Android application with Gradle and Android Studio. Now we can start
 defining a new API for talking with Eliza!
 
-## Define a Protobuf service
+## Define a service
 
-In the shell, create a proto directory to keep the `.proto` files in.
+First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program.
 
 ```bash
-$ mkdir proto
-$ cd proto
+$ mkdir -p proto && touch proto/eliza.proto
 ```
 
-Next, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf mod init`.
+Open up the above file and add the following service definition:
 
-```bash
-$ buf mod init
-```
+```proto
+syntax = "proto3";
 
-We have already defined the `ElizaService` and have
-it [hosted on the Buf Schema Registry][eliza-proto] to use in this example.
-Export the Protobuf schema to use in our project.
+package connectrpc.eliza.v1;
 
-```bash title="~/.../Eliza/proto"
-$ buf export buf.build/connectrpc/eliza -o .
-```
+message SayRequest {
+  string sentence = 1;
+}
 
-Our new `proto` directory should look like this:
+message SayResponse {
+  string sentence = 1;
+}
 
-```
-proto
-├── connectrpc
-│   └── eliza
-│       └── v1
-│           └── eliza.proto
-└── buf.yaml
+service ElizaService {
+  rpc Say(SayRequest) returns (SayResponse) {}
+}
 ```
 
 Open the newly created `eliza.proto` file in the editor.
@@ -98,20 +92,36 @@ are the input and output for the `Say` RPC method.
 We're going to generate our code using [`buf`][buf], a modern replacement for
 Google's protobuf compiler.
 
-```bash
-$ cd ..
-$ touch buf.gen.yaml
+First, scaffold a basic [`buf.yaml`][buf.yaml] by running `buf config init` at the root of your repository. Then, edit `buf.yaml`
+to use our `proto` directory:
+
+```yaml title=buf.yaml
+version: v2
+// highlight-next-line
+modules:
+// highlight-next-line
+  - path: proto
+lint:
+  use:
+    - DEFAULT
+breaking:
+  use:
+    - FILE
 ```
 
 We will use [_remote plugins_][remote-plugins], a feature of the [Buf Schema Registry][bsr] for generating code. Tell `buf`
-how to generate code by putting this into [`buf.gen.yaml`][buf.gen.yaml]:
+how to generate code by creating a [`buf.gen.yaml`][buf.gen.yaml]:
+
+```bash
+$ touch buf.gen.yaml
+```
 
 ```yaml title=buf.gen.yaml
-version: v1
+version: v2
 plugins:
-  - plugin: buf.build/protocolbuffers/java
+  - remote: buf.build/protocolbuffers/java
     out: app/src/main/java
-  - plugin: buf.build/connectrpc/kotlin
+  - remote: buf.build/connectrpc/kotlin
     out: app/src/main/java
 ```
 
@@ -134,7 +144,8 @@ With those configuration files in place, generating Kotlin code
 can be easily done:
 
 ```bash
-$ buf generate proto
+$ buf lint
+$ buf generate
 ```
 
 In the `app/src/main/java` directory, there should now be some generated Java and Kotlin files:
@@ -668,9 +679,9 @@ the Connect-Kotlin repository on GitHub. These examples demonstrate:
 
 [buf-cli]: https://buf.build/docs/installation
 
-[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml
+[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml
 
-[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml
+[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml
 
 [connect-go]: https://github.com/connectrpc/connect-go
 

diff --git a/docs/node/getting-started.md b/docs/node/getting-started.md
@@ -39,18 +39,15 @@ $ npm install @bufbuild/buf @bufbuild/protoc-gen-es @bufbuild/protobuf @connectr
 
 ## Define a service
 
-First, we need to add a Protobuf file that includes our service definition. For
-this tutorial, we are going to construct a unary endpoint for a service that is
-a stripped-down implementation of [ELIZA](https://en.wikipedia.org/wiki/ELIZA),
-the famous natural language processing program.
+First, we need to add a Protobuf file that includes our service definition. For this tutorial, we are going to construct a unary endpoint for a service that is a stripped-down implementation of ELIZA, the famous natural language processing program.
 
 ```bash
 $ mkdir -p proto && touch proto/eliza.proto
 ```
 
 Open up the above file and add the following service definition:
 
-```protobuf
+```proto
 syntax = "proto3";
 
 package connectrpc.eliza.v1;
@@ -76,42 +73,68 @@ but we also need a configuration file to get going. (If you'd prefer, you can
 skip this section and use `protoc` instead &mdash; `protoc-gen-connect-es`
 behaves like any other plugin.)
 
-First, tell Buf how to generate code with a `buf.gen.yaml` file:
+First, scaffold a basic [`buf.yaml`][buf.yaml] at the root of your repository:
+
+```bash
+$ npx buf config init
+```
+
+Then, edit `buf.yaml` to use our `proto` directory:
+
+```yaml title=buf.yaml
+version: v2
+// highlight-next-line
+modules:
+// highlight-next-line
+  - path: proto
+lint:
+  use:
+    - DEFAULT
+breaking:
+  use:
+    - FILE
+```
+
+
+Next, tell Buf how to generate code by putting this into
+[`buf.gen.yaml`][buf.gen.yaml]:
 
 ```yaml
-version: v1
+version: v2
 plugins:
-  - plugin: es
-    opt: target=ts
+  - local: protoc-gen-es
     out: gen
-  - plugin: connect-es
     opt: target=ts
+  - local: protoc-gen-connect-es
     out: gen
+    opt: target=ts
 ```
 
-With this file in place, you can generate code from the schema in the `proto`
-directory:
+With those configuration files in place, you can lint your schema and generate
+code:
 
 ```bash
-$ npx buf generate proto
+$ npx buf lint
+$ npx buf generate
 ```
 
 You should now see two generated TypeScript files:
 
 ```diff
 .
 ├── buf.gen.yaml
+├── buf.yaml
 // highlight-next-line
 ├── gen
 // highlight-next-line
-│   ├── eliza_connect.ts
+│   ├── eliza_connect.ts
 // highlight-next-line
-│   └── eliza_pb.ts
+│   └── eliza_pb.ts
 ├── node_modules
 ├── package-lock.json
 ├── package.json
 ├── proto
-│   └── eliza.proto
+│   └── eliza.proto
 └── tsconfig.json
 ```
 
@@ -351,3 +374,8 @@ supports both the gRPC and Connect protocols. Unlike a hand-written REST service
 you didn't need to design a URL hierarchy, hand-write request and response
 objects, or parse typed values out of query parameters. More importantly,
 your users got an idiomatic, type-safe client without any extra work on your part.
+
+[buf]: https://www.npmjs.com/package/@bufbuild/buf
+[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml
+[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml
+[eliza-proto]: https://buf.build/connectrpc/eliza/file/main:connectrpc/eliza/v1/eliza.proto
diff --git a/docs/swift/generating-code.md b/docs/swift/generating-code.md
@@ -64,26 +64,25 @@ When developing a new project, 2 new files need to be created:
 The first file, `buf.yaml`, can be created by running:
 
 ```bash
-buf mod init
+buf config init
 ```
 
 The second file, `buf.gen.yaml`, needs to be created manually and specifies
 which plugins should be used to generate code. An example of this
 file is shown below:
 
 ```yaml
-version: v1
+version: v2
 plugins:
-  - plugin: buf.build/connectrpc/swift
+  - remote: buf.build/connectrpc/swift
+    out: Generated
     opt:
       - GenerateAsyncMethods=true
       - GenerateCallbackMethods=true
       - Visibility=Public
+  - remote: buf.build/apple/swift
     out: Generated
-  - plugin: buf.build/apple/swift
-    opt:
-      - Visibility=Public
-    out: Generated
+    opt: Visibility=Public
 ```
 
 This file specifies that the [`connect-swift` plugin][connect-swift-plugin]
@@ -135,18 +134,17 @@ local generation, except the `buf.gen.yaml` file should be modified to use
 local plugins instead of remote plugins:
 
 ```yaml
-version: v1
+version: v2
 plugins:
-  - plugin: connect-swift # protoc-gen-connect-swift in your PATH
+  - local: protoc-gen-connect-swift # protoc-gen-connect-swift in your PATH
+    out: Generated
     opt:
       - GenerateAsyncMethods=true
       - GenerateCallbackMethods=true
       - Visibility=Public
+  - local: protoc-gen-swift # protoc-gen-swift in your PATH
     out: Generated
-  - plugin: swift # protoc-gen-swift in your PATH
-    opt:
-      - Visibility=Public
-    out: Generated
+    opt: Visibility=Public
 ```
 
 ## Using generated code
@@ -187,8 +185,8 @@ the `buf.gen.yaml` file as shown in the example above.
 
 [available-plugins]: https://buf.build/plugins
 [buf]: https://buf.build/docs/
-[buf.gen.yaml]: https://buf.build/docs/configuration/v1/buf-gen-yaml
-[buf.yaml]: https://buf.build/docs/configuration/v1/buf-yaml
+[buf.gen.yaml]: https://buf.build/docs/configuration/v2/buf-gen-yaml
+[buf.yaml]: https://buf.build/docs/configuration/v2/buf-yaml
 [buf-cli]: https://buf.build/docs/installation
 [connect-swift]: https://github.com/connectrpc/connect-swift
 [connect-swift-mocks-plugin]: https://buf.build/connectrpc/swift-mocks