Add migration guide doc (#74)

Improve the documentation for migrating from the individual actions. --------- Co-authored-by: Nick Snyder <[email protected]>
bufbuild · Oct 19, 2024 · 7997a8a · 7997a8a
1 parent 3fb7035
commit 7997a8a
Show file tree

Hide file tree

Showing 2 changed files with 147 additions and 1 deletion.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,144 @@
+# Migration Guide
+
+This guide explains what changed when migrating from the individual Buf actions
+([buf-setup-action][buf-setup], [buf-breaking-action][buf-breaking],
+[buf-lint-action][buf-lint], [buf-push-action][buf-push]) to the new
+consolidated `buf-action`.
+
+## [buf-setup-action][buf-setup]
+
+To migrate from `buf-setup-action` to `buf-action`, refer to the table below for the necessary changes:
+
+| Old Parameter       | New Parameter       | Description         |
+|:--------------------|:--------------------|:--------------------|
+| `version`           | `version`           | Unchanged. Version of `buf` CLI to install. |
+| `buf_user`          | N/A                 | Removed. The username is not required for login. |
+| `buf_api_token`     | `token`             | Renamed. Buf API token for BSR requests. |
+| `buf_domain`        | `domain`            | Renamed. Buf domain for BSR requests. Enterprise only. |
+| N/A                 | `setup_only`        | Added. Installs `buf` and optionally login to the BSR but no additional commands will be run. Set to `true` to make `buf-action` behave like `buf-setup-action`. Defaults to `false`. For more details, refer to the setup-only example in the [README](./README.md#setup-only) |
+| N/A                 | `github_action`     | Added. Github actor for API requests. Defaults to the current actor in the Github context. |
+| `github_token`      | `github_token`      | Unchanged. GitHub token for API requests. Defaults to token in the Github Context. |
+
+Example migration:
+
+```diff
+ steps:
+   - uses: actions/checkout@v4
+-  - uses: bufbuild/[email protected]
++  - uses: bufbuild/buf-action@v1
+     with:
+-      buf_user: ${{ secrets.buf_user }}
+-      buf_api_token: ${{ secrets.buf_api_token }}
++      version: '1.45.0' # Optional. Defaults to the latest release.
++      token: ${{ secrets.buf_api_token }}
++      setup_only: true
+   - run: buf --version
+```
+
+> [!NOTE]
+> The `buf` CLI version is no longer dependent on the action version.
+
+## [buf-breaking-action][buf-breaking]
+
+To migrate from `buf-breaking-action` to `buf-action`, refer to the table below for the necessary changes:
+
+| Old Parameter       | New Parameter       | Description                                                      |
+|:--------------------|:--------------------|:-----------------------------------------------------------------|
+| `input`             | `input`             | Unchanged. The input directory to build. Defaults to the current directory. See the [README](./README.md#specify-the-input-directory) for more details on specifying inputs. | 
+| `against`           | `breaking_against`  | Renamed. Specifies the reference to check breaking changes against. We recommend not setting this parameter and instead relying on the default behavior. |
+| `buf_input_https_username`| N/A           | Removed. The username is not required for login. |
+| `buf_input_https_password`| N/A           | Removed. To support multiple registries use the mulitple format of `BUF_TOKEN` as an enviornemt variable. See the [buf token formats documentation][buf-token-formats] for more details.  |
+| `buf_token`         | `token`             | Renamed. Buf API token for BSR requests.                          |
+
+Example migration:
+
+```diff
+ steps:
+   - uses: actions/checkout@v4
+-  - uses: bufbuild/buf-setup-action@v1
+-  - uses: bufbuild/buf-breaking-action@v1
++  - uses: bufbuild/buf-action@v1
+     with:
+-      buf_token: ${{ secrets.BUF_TOKEN }}
++      token: ${{ secrets.BUF_TOKEN }}
+-      against: 'https://github.com/acme/weather.git#branch=main'
++      # This example shows how to maintain behavior when migrating, but we recommend unsetting this parameter and relying on the default behavior instead.
++      breaking_against: 'https://github.com/acme/weather.git#branch=main'
+```
+
+## [buf-lint-action][buf-lint]
+
+To migrate from `buf-lint-action` to `buf-action`, refer to the table below for the necessary changes.
+
+| Old Parameter       | New Parameter       | Description                                                      |
+|:--------------------|:--------------------|:-----------------------------------------------------------------|
+| `input`             | `input`             | Unchanged. The input directory to lint. Defaults to the current directory. See the [README](./README.md#specify-the-input-directory) for more details on specifying inputs. | 
+| `buf_token`         | `token`             | Renamed. Buf API token for BSR requests.                          |
+
+Example migration:
+
+```diff
+ steps:
+   - uses: actions/checkout@v4
+-  - uses: bufbuild/buf-setup-action@v1
+-  - uses: bufbuild/buf-lint-action@v1
++  - uses: bufbuild/buf-action@v1
+     with:
+       input: proto
+-      buf_token: ${{ secrets.BUF_TOKEN }}
++      token: ${{ secrets.BUF_TOKEN }}
+```
+
+## [buf-push-action][buf-push]
+
+To migrate from `buf-push-action` to `buf-action`, refer to the table below for the necessary changes:
+
+| Old Parameter       | New Parameter       | Description                                                      |
+|:--------------------|:--------------------|:-----------------------------------------------------------------|
+| `input`             | `input`             | Unchanged. The input directory to push. Defaults to the current directory. See the [README](./README.md#specify-the-input-directory) for more details on specifying inputs. | 
+| `buf_token`         | `token`             | Renamed. Buf API token for BSR requests.                          |
+| `draft`             | N/A                 | Removed. Drafts are deprecated in favor of labels. Labels are set using [git metadata][git-metadata]. |
+| `create_visibility` | N/A                 | Removed. Repositories will always be created with `private` visibility if they do not exist. |
+| N/A                 | `push_disable_create`| Added. Disables automatic creation of repositories. Defaults to `false`. |
+
+Example migration:
+
+```diff
+ steps:
+   - uses: actions/checkout@v4
+-  - uses: bufbuild/buf-setup-action@v1
+-  - uses: bufbuild/buf-push-action@v1
++  - uses: bufbuild/buf-action@v1
+     with:
+-      buf_token: ${{ secrets.BUF_TOKEN }}
++      token: ${{ secrets.BUF_TOKEN }}
+-      create_visibility: private
+-      draft: ${{ github.ref_name != 'main'}}
+```
+
+To further customize the push action call the `buf push` command directly. 
+For example:
+
+```diff
+ steps:
+   - uses: actions/checkout@v4
+   - uses: bufbuild/buf-action@v1
+      with:
+        token: ${{ secrets.BUF_TOKEN }}
++       setup_only: true # Disables default behavior.
++  - if: ${{ github.event_name == 'push' }}
++    run: buf push --error-format github-actions --create --git-metadata
+```
+
+> [!NOTE]
+> Labels are a new feature in the `buf` CLI. For more information, see the [commits and labels][commits-labels] documentation.
+
+[buf]: https://buf.build  
+[buf-setup]: https://github.com/marketplace/actions/buf-setup  
+[buf-breaking]: https://github.com/marketplace/actions/buf-breaking  
+[buf-cli]: https://github.com/bufbuild/buf  
+[buf-lint]: https://github.com/marketplace/actions/buf-lint  
+[buf-push]: https://github.com/marketplace/actions/buf-push
+[git-metadata]: https://buf.build/docs/reference/cli/buf/push/?h=git+metadata#git-metadata
+[buf-token-formats]: https://buf.build/docs/bsr/authentication/#buf_token-formats
+[commits-labels]: https://buf.build/docs/concepts/commits-labels/
diff --git a/README.md b/README.md
@@ -168,7 +168,7 @@ jobs:
 
 ### Specify the input directory
 
-To run the action for parameters not declared at the root of the repository,
+To run the action for inputs not declared at the root of the repository,
 set the parameter `input` to the directory of your `buf.yaml` file.
 
 ```yaml
@@ -281,6 +281,8 @@ we recommend migrating to this consolidated action that has additional capabilit
 - Status comments on pull requests.
 - Easy configuration for custom behavior.
 
+See the [migration guide](MIGRATION.md) for more information.
+
 ## Feedback and support
 
 If you have any feedback or need support, please reach out to us on the [Buf Slack][slack],