diff --git a/.bcr/README.md b/.bcr/README.md new file mode 100644 index 00000000..95547d9f --- /dev/null +++ b/.bcr/README.md @@ -0,0 +1,163 @@ +# Bazel Central Registry (BCR) Publishing + +This directory contains configuration files for automatically publishing `fast_float` releases to the [Bazel Central Registry (BCR)](https://github.com/bazelbuild/bazel-central-registry). + +## Overview + +When a new release is published on GitHub, the workflow defined in `.github/workflows/publish-to-bcr.yml` automatically: +1. Creates a new entry in the BCR with the release version +2. Opens a pull request to the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository +3. Allows BCR maintainers to review and merge the update + +This makes the new version of `fast_float` available to all Bazel users through the standard module system. + +## Files in This Directory + +### `metadata.template.json` +Contains repository metadata including: +- Project homepage +- Maintainer information (name, email, GitHub username) +- Repository references + +This information is used to populate the BCR entry's `metadata.json` file. + +### `source.template.json` +Defines how to fetch the source code for each release: +- URL pattern for release archives +- Archive strip prefix configuration +- Integrity hash (auto-generated during publishing) + +### `presubmit.yml` +Specifies the CI tests that BCR will run before accepting a new version: +- Platforms to test on (Linux, macOS, Windows) +- Bazel versions to test with +- Build targets to verify + +## How the Publishing Workflow Works + +The publishing process is automated through GitHub Actions: + +1. **Trigger**: When you create a new release on GitHub (or manually trigger the workflow) +2. **Build**: The workflow uses [bazel-contrib/publish-to-bcr](https://github.com/bazel-contrib/publish-to-bcr) reusable workflow +3. **Generate**: Creates BCR entry files from the templates in this directory +4. **Submit**: Opens a pull request to the Bazel Central Registry +5. **Review**: BCR maintainers review and merge the PR + +## Setting Up the Personal Access Token (PAT) + +The publishing workflow requires a GitHub Personal Access Token with appropriate permissions to: +- Push to a fork of the Bazel Central Registry +- Open pull requests against the upstream BCR + +### Creating a Personal Access Token + +1. **Navigate to GitHub Settings** + - Go to https://github.com/settings/tokens + - Or: Click your profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic) + +2. **Generate New Token** + - Click "Generate new token (classic)" + - Give it a descriptive name, e.g., "BCR Publishing for fast_float" + - Set an appropriate expiration (recommended: 1 year with calendar reminder to renew) + +3. **Select Required Scopes** + - ✅ **`repo`** (Full control of private repositories) - Required for accessing repository details + - ✅ **`workflow`** (Update GitHub Action workflows) - Required for the publishing action + +4. **Generate and Copy** + - Click "Generate token" at the bottom + - **Important**: Copy the token immediately - you won't be able to see it again! + +5. **Add as Repository Secret** + - Go to the fast_float repository settings + - Navigate to: Settings → Secrets and variables → Actions + - Click "New repository secret" + - Name: `BCR_PUBLISH_TOKEN` + - Value: Paste the token you copied + - Click "Add secret" + +### Important Notes + +- **Classic PATs vs Fine-grained PATs**: Currently, you must use a "Classic" PAT. Fine-grained PATs don't yet support opening pull requests against public repositories (though GitHub is working on this). + +- **Token Security**: Keep the token secure and never commit it to the repository. GitHub Secrets are encrypted and only exposed to authorized workflows. + +- **Token Expiration**: Set a calendar reminder before your token expires to generate a new one, otherwise the publishing workflow will fail. + +- **Permissions Required**: The token needs both `repo` and `workflow` scopes to function properly. + +## Fork Requirements + +The publishing workflow requires a fork of the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository: + +- The fork should be in the repository owner's account or organization +- The PAT must have write access to this fork +- The workflow will push changes to the fork and open PRs from there to the upstream BCR + +## Manual Triggering + +You can manually trigger the publishing workflow: + +1. Go to the Actions tab in the GitHub repository +2. Select "Publish to BCR" workflow +3. Click "Run workflow" +4. Enter the tag name (e.g., `v6.1.6`) +5. Click "Run workflow" + +This is useful for: +- Republishing a release if the automatic workflow failed +- Publishing an older release that wasn't automatically published +- Testing the workflow + +## Troubleshooting + +### Publishing Workflow Fails + +1. **Check the workflow logs** in the Actions tab for specific error messages +2. **Verify the PAT** is still valid and has the correct permissions +3. **Confirm the fork exists** and the PAT has access to it +4. **Check the template files** in this directory are valid JSON + +### Pull Request Not Opening + +1. **Verify PAT permissions** - must include `repo` and `workflow` scopes +2. **Check fork configuration** - ensure the BCR fork exists and is accessible +3. **Review workflow inputs** - ensure the tag name matches the actual release tag + +### BCR Presubmit Tests Fail + +1. **Review presubmit.yml** to ensure test configuration is correct +2. **Check build targets** are valid in the new version +3. **Verify MODULE.bazel** and BUILD files are properly configured +4. The BCR maintainers may provide feedback on the pull request + +## Updating Configuration + +### To Update Maintainer Information + +Edit `metadata.template.json` and update the maintainers array. + +### To Change Test Configuration + +Edit `presubmit.yml` to modify: +- Platforms to test on +- Bazel versions to test with +- Build targets to verify + +### To Modify Source Archive Settings + +Edit `source.template.json` if the release archive structure changes. + +## Resources + +- [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry) +- [publish-to-bcr Documentation](https://github.com/bazel-contrib/publish-to-bcr) +- [Bzlmod User Guide](https://bazel.build/docs/bzlmod) +- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) + +## Support + +If you encounter issues with BCR publishing: +1. Check the [publish-to-bcr issues](https://github.com/bazel-contrib/publish-to-bcr/issues) +2. Review [BCR submission guidelines](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md) +3. Open an issue in the fast_float repository for project-specific problems diff --git a/.bcr/metadata.template.json b/.bcr/metadata.template.json new file mode 100644 index 00000000..29e5954a --- /dev/null +++ b/.bcr/metadata.template.json @@ -0,0 +1,16 @@ +{ + "homepage": "https://github.com/fastfloat/fast_float", + "maintainers": [ + { + "email": "daniel@lemire.me", + "github": "lemire", + "name": "Daniel Lemire", + "github_user_id": 391987 + } + ], + "repository": [ + "github:fastfloat/fast_float" + ], + "versions": [], + "yanked_versions": {} +} diff --git a/.bcr/presubmit.yml b/.bcr/presubmit.yml new file mode 100644 index 00000000..50ce5f29 --- /dev/null +++ b/.bcr/presubmit.yml @@ -0,0 +1,20 @@ +matrix: + platform: + - debian10 + - ubuntu2004 + - ubuntu2204 + - macos + - macos_arm64 + - windows + bazel: + - 9.* + - 8.x + - 7.x + - 6.x +tasks: + verify_targets: + name: Verify build targets + platform: ${{ platform }} + bazel: ${{ bazel }} + build_targets: + - '@fast_float' diff --git a/.bcr/source.template.json b/.bcr/source.template.json new file mode 100644 index 00000000..9b00d13a --- /dev/null +++ b/.bcr/source.template.json @@ -0,0 +1,5 @@ +{ + "integrity": "", + "strip_prefix": "{REPO}-{VERSION}", + "url": "https://github.com/{OWNER}/{REPO}/archive/refs/tags/v{VERSION}.tar.gz" +} diff --git a/.github/workflows/publish-to-bcr.yml b/.github/workflows/publish-to-bcr.yml new file mode 100644 index 00000000..1e9a1ef8 --- /dev/null +++ b/.github/workflows/publish-to-bcr.yml @@ -0,0 +1,26 @@ +name: Publish to BCR + +on: + release: + types: [published] + + # Allow manual triggering from GH UI + workflow_dispatch: + inputs: + tag_name: + description: 'Tag name to publish (e.g., v1.2.3)' + required: true + type: string + +permissions: + id-token: write + attestations: write + contents: write + +jobs: + publish: + uses: bazel-contrib/publish-to-bcr/.github/workflows/publish.yaml@v1.0.0 + with: + tag_name: ${{ github.event.release.tag_name || inputs.tag_name }} + secrets: + publish_token: ${{ secrets.BCR_PUBLISH_TOKEN }}