docs: align config and github workflow (#314)
* docs: align config and positioning copy * docs: remove internal branch workflow residue * docs: record github sync guard * chore: retrigger commit lint * docs: leave readme files unchanged * docs: remove public positioning comparison
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# GitHub Sync Guard
|
||||
|
||||
This page records the GitHub-only files that must be preserved when refreshing
|
||||
this public repository from the internal GitLab source/export.
|
||||
|
||||
## Rule
|
||||
|
||||
When a GitLab export, archive, rsync, or scripted copy is used to refresh the
|
||||
GitHub repository, do **not** blindly overwrite GitHub-only contributor,
|
||||
automation, and public-facing workflow files.
|
||||
|
||||
These files describe the public GitHub workflow: protected `main`, scoped
|
||||
branches, GitHub pull requests, GitHub Actions, and community contribution
|
||||
rules. Internal workflow text can mislead contributors and AI coding tools if
|
||||
it is copied into GitHub.
|
||||
|
||||
## Preserve These GitHub Files
|
||||
|
||||
Keep the GitHub versions of these files unless a maintainer deliberately updates
|
||||
them for the public GitHub workflow:
|
||||
|
||||
- `CLAUDE.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md`
|
||||
- `.github/BRANCH_PROTECTION.md`
|
||||
- `.github/workflows/ci.yml`
|
||||
- `.github/workflows/docs.yml`
|
||||
- `.github/workflows/commits.yml`
|
||||
- `.github/ISSUE_TEMPLATE/**`
|
||||
- `.claude/skills/commit/SKILL.md`
|
||||
- `.claude/skills/new-branch/SKILL.md`
|
||||
- `.claude/skills/pr/SKILL.md`
|
||||
- `scripts/check_github_contributor_docs.py`
|
||||
- `tests/unit/test_scripts/test_check_github_contributor_docs.py`
|
||||
|
||||
## Safe Sync Pattern
|
||||
|
||||
Prefer an explicit exclude list in the sync job rather than manual cleanup after
|
||||
the overwrite. Example shape:
|
||||
|
||||
```bash
|
||||
rsync -a --delete \
|
||||
--exclude 'CLAUDE.md' \
|
||||
--exclude 'CONTRIBUTING.md' \
|
||||
--exclude '.github/PULL_REQUEST_TEMPLATE.md' \
|
||||
--exclude '.github/BRANCH_PROTECTION.md' \
|
||||
--exclude '.github/workflows/ci.yml' \
|
||||
--exclude '.github/workflows/docs.yml' \
|
||||
--exclude '.github/workflows/commits.yml' \
|
||||
--exclude '.github/ISSUE_TEMPLATE/' \
|
||||
--exclude '.claude/skills/commit/SKILL.md' \
|
||||
--exclude '.claude/skills/new-branch/SKILL.md' \
|
||||
--exclude '.claude/skills/pr/SKILL.md' \
|
||||
--exclude 'scripts/check_github_contributor_docs.py' \
|
||||
--exclude 'tests/unit/test_scripts/test_check_github_contributor_docs.py' \
|
||||
<gitlab-export>/ <github-checkout>/
|
||||
```
|
||||
|
||||
After any sync, run:
|
||||
|
||||
```bash
|
||||
make docs-check
|
||||
make lint
|
||||
```
|
||||
|
||||
The `check_github_contributor_docs.py` gate catches the known failure mode:
|
||||
public contributor docs drifting back to an internal branch/review model.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Before opening a sync PR:
|
||||
|
||||
- Confirm `CLAUDE.md` says branches are created from `main`.
|
||||
- Confirm `.claude/skills/pr/SKILL.md` creates PRs with `--base main`.
|
||||
- Confirm `CONTRIBUTING.md` says GitHub pull request, not internal review
|
||||
terminology.
|
||||
- Confirm `make docs-check` and `make lint` both pass.
|
||||
Reference in New Issue
Block a user