Skip to content

Commit 38ecb65

Browse files
CopilotCopilot
authored
Add BCR maintainer documentation with PAT setup instructions
1 parent eba6e93 commit 38ecb65

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎.bcr/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Bazel Central Registry (BCR) Publishing
2+
3+
This directory contains configuration files for automatically publishing `fast_float` releases to the [Bazel Central Registry (BCR)](https://github.com/bazelbuild/bazel-central-registry).
4+
5+
## Overview
6+
7+
When a new release is published on GitHub, the workflow defined in `.github/workflows/publish-to-bcr.yml` automatically:
8+
1. Creates a new entry in the BCR with the release version
9+
2. Opens a pull request to the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository
10+
3. Allows BCR maintainers to review and merge the update
11+
12+
This makes the new version of `fast_float` available to all Bazel users through the standard module system.
13+
14+
## Files in This Directory
15+
16+
### `metadata.template.json`
17+
Contains repository metadata including:
18+
- Project homepage
19+
- Maintainer information (name, email, GitHub username)
20+
- Repository references
21+
22+
This information is used to populate the BCR entry's `metadata.json` file.
23+
24+
### `source.template.json`
25+
Defines how to fetch the source code for each release:
26+
- URL pattern for release archives
27+
- Archive strip prefix configuration
28+
- Integrity hash (auto-generated during publishing)
29+
30+
### `presubmit.yml`
31+
Specifies the CI tests that BCR will run before accepting a new version:
32+
- Platforms to test on (Linux, macOS, Windows)
33+
- Bazel versions to test with
34+
- Build targets to verify
35+
36+
## How the Publishing Workflow Works
37+
38+
The publishing process is automated through GitHub Actions:
39+
40+
1. **Trigger**: When you create a new release on GitHub (or manually trigger the workflow)
41+
2. **Build**: The workflow uses [bazel-contrib/publish-to-bcr](https://github.com/bazel-contrib/publish-to-bcr) reusable workflow
42+
3. **Generate**: Creates BCR entry files from the templates in this directory
43+
4. **Submit**: Opens a pull request to the Bazel Central Registry
44+
5. **Review**: BCR maintainers review and merge the PR
45+
46+
## Setting Up the Personal Access Token (PAT)
47+
48+
The publishing workflow requires a GitHub Personal Access Token with appropriate permissions to:
49+
- Push to a fork of the Bazel Central Registry
50+
- Open pull requests against the upstream BCR
51+
52+
### Creating a Personal Access Token
53+
54+
1. **Navigate to GitHub Settings**
55+
- Go to https://github.com/settings/tokens
56+
- Or: Click your profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic)
57+
58+
2. **Generate New Token**
59+
- Click "Generate new token (classic)"
60+
- Give it a descriptive name, e.g., "BCR Publishing for fast_float"
61+
- Set an appropriate expiration (recommended: 1 year with calendar reminder to renew)
62+
63+
3. **Select Required Scopes**
64+
- ✅ **`repo`** (Full control of private repositories) - Required for accessing repository details
65+
- ✅ **`workflow`** (Update GitHub Action workflows) - Required for the publishing action
66+
67+
4. **Generate and Copy**
68+
- Click "Generate token" at the bottom
69+
- **Important**: Copy the token immediately - you won't be able to see it again!
70+
71+
5. **Add as Repository Secret**
72+
- Go to the fast_float repository settings
73+
- Navigate to: Settings → Secrets and variables → Actions
74+
- Click "New repository secret"
75+
- Name: `BCR_PUBLISH_TOKEN`
76+
- Value: Paste the token you copied
77+
- Click "Add secret"
78+
79+
### Important Notes
80+
81+
- **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).
82+
83+
- **Token Security**: Keep the token secure and never commit it to the repository. GitHub Secrets are encrypted and only exposed to authorized workflows.
84+
85+
- **Token Expiration**: Set a calendar reminder before your token expires to generate a new one, otherwise the publishing workflow will fail.
86+
87+
- **Permissions Required**: The token needs both `repo` and `workflow` scopes to function properly.
88+
89+
## Fork Requirements
90+
91+
The publishing workflow requires a fork of the [bazel-central-registry](https://github.com/bazelbuild/bazel-central-registry) repository:
92+
93+
- The fork should be in the repository owner's account or organization
94+
- The PAT must have write access to this fork
95+
- The workflow will push changes to the fork and open PRs from there to the upstream BCR
96+
97+
## Manual Triggering
98+
99+
You can manually trigger the publishing workflow:
100+
101+
1. Go to the Actions tab in the GitHub repository
102+
2. Select "Publish to BCR" workflow
103+
3. Click "Run workflow"
104+
4. Enter the tag name (e.g., `v6.1.6`)
105+
5. Click "Run workflow"
106+
107+
This is useful for:
108+
- Republishing a release if the automatic workflow failed
109+
- Publishing an older release that wasn't automatically published
110+
- Testing the workflow
111+
112+
## Troubleshooting
113+
114+
### Publishing Workflow Fails
115+
116+
1. **Check the workflow logs** in the Actions tab for specific error messages
117+
2. **Verify the PAT** is still valid and has the correct permissions
118+
3. **Confirm the fork exists** and the PAT has access to it
119+
4. **Check the template files** in this directory are valid JSON
120+
121+
### Pull Request Not Opening
122+
123+
1. **Verify PAT permissions** - must include `repo` and `workflow` scopes
124+
2. **Check fork configuration** - ensure the BCR fork exists and is accessible
125+
3. **Review workflow inputs** - ensure the tag name matches the actual release tag
126+
127+
### BCR Presubmit Tests Fail
128+
129+
1. **Review presubmit.yml** to ensure test configuration is correct
130+
2. **Check build targets** are valid in the new version
131+
3. **Verify MODULE.bazel** and BUILD files are properly configured
132+
4. The BCR maintainers may provide feedback on the pull request
133+
134+
## Updating Configuration
135+
136+
### To Update Maintainer Information
137+
138+
Edit `metadata.template.json` and update the maintainers array.
139+
140+
### To Change Test Configuration
141+
142+
Edit `presubmit.yml` to modify:
143+
- Platforms to test on
144+
- Bazel versions to test with
145+
- Build targets to verify
146+
147+
### To Modify Source Archive Settings
148+
149+
Edit `source.template.json` if the release archive structure changes.
150+
151+
## Resources
152+
153+
- [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry)
154+
- [publish-to-bcr Documentation](https://github.com/bazel-contrib/publish-to-bcr)
155+
- [Bzlmod User Guide](https://bazel.build/docs/bzlmod)
156+
- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
157+
158+
## Support
159+
160+
If you encounter issues with BCR publishing:
161+
1. Check the [publish-to-bcr issues](https://github.com/bazel-contrib/publish-to-bcr/issues)
162+
2. Review [BCR submission guidelines](https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md)
163+
3. Open an issue in the fast_float repository for project-specific problems

0 commit comments

Comments
 (0)