fast_float/.bcr

Bazel Central Registry (BCR) Publishing

This directory contains configuration files for automatically publishing fast_float releases to the Bazel Central Registry (BCR).

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 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 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 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
• publish-to-bcr Documentation
• Bzlmod User Guide
• GitHub PAT Documentation

Support

If you encounter issues with BCR publishing:

1. Check the publish-to-bcr issues
2. Review BCR submission guidelines
3. Open an issue in the fast_float repository for project-specific problems