Add migration guide doc (#74)

Improve the documentation for migrating from the individual actions.

---------

Co-authored-by: Nick Snyder <nsnyder@buf.build>

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/buf-setup-action@v1.45.0
++ - 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/

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],