111 lines
4.0 KiB
Markdown
111 lines
4.0 KiB
Markdown
# Phase 4: Publish to GitHub
|
|
|
|
## Goal
|
|
|
|
Make Harmony publicly available on GitHub as the primary community hub for issues, pull requests, and discussions. CI runs on self-hosted runners.
|
|
|
|
## Prerequisites
|
|
|
|
- Phase 3 complete: LFS removed, git history cleaned, repo is small
|
|
- README polished with quick-start, architecture overview, examples
|
|
- All existing tests pass
|
|
|
|
## Tasks
|
|
|
|
### 4.1 Clean git history
|
|
|
|
```bash
|
|
# Option A: git filter-repo (preferred)
|
|
git filter-repo --strip-blobs-bigger-than 10M
|
|
|
|
# Option B: BFG Repo Cleaner
|
|
bfg --strip-blobs-bigger-than 10M
|
|
git reflog expire --expire=now --all
|
|
git gc --prune=now --aggressive
|
|
```
|
|
|
|
Verify final repo size is reasonable (target: <50MB including all code, docs, templates).
|
|
|
|
### 4.2 Create GitHub repository
|
|
|
|
- Create `NationTech/harmony` (or chosen org/name) on GitHub
|
|
- Push cleaned repo as initial commit
|
|
- Set default branch to `main` (rename from `master` if desired)
|
|
|
|
### 4.3 Set up CI on self-hosted runners
|
|
|
|
GitHub is the community hub, but CI runs on your own infrastructure. Options:
|
|
|
|
**Option A: GitHub Actions with self-hosted runners**
|
|
- Register your Gitea runner machines as GitHub Actions self-hosted runners
|
|
- Port `.gitea/workflows/check.yml` to `.github/workflows/check.yml`
|
|
- Same Docker image (`hub.nationtech.io/harmony/harmony_composer:latest`), same commands
|
|
- Pro: native GitHub PR checks, no external service needed
|
|
- Con: runners need outbound access to GitHub API
|
|
|
|
**Option B: External CI (Woodpecker, Drone, Jenkins)**
|
|
- Use any CI that supports webhooks from GitHub
|
|
- Report status back to GitHub via commit status API / checks API
|
|
- Pro: fully self-hosted, no GitHub dependency for builds
|
|
- Con: extra integration work
|
|
|
|
**Option C: Keep Gitea CI, mirror from GitHub**
|
|
- GitHub repo has a webhook that triggers Gitea CI on push
|
|
- Gitea reports back to GitHub via commit status API
|
|
- Pro: no migration of CI config
|
|
- Con: fragile webhook chain
|
|
|
|
**Recommendation**: Option A. GitHub Actions self-hosted runners are straightforward and give the best contributor UX (native PR checks). The workflow files are nearly identical to Gitea workflows.
|
|
|
|
```yaml
|
|
# .github/workflows/check.yml
|
|
name: Check
|
|
on: [push, pull_request]
|
|
jobs:
|
|
check:
|
|
runs-on: self-hosted
|
|
container:
|
|
image: hub.nationtech.io/harmony/harmony_composer:latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- run: bash build/check.sh
|
|
```
|
|
|
|
### 4.4 Polish documentation
|
|
|
|
- **README.md**: Quick-start (clone → run → get prompted → see result), architecture diagram (Score → Interpret → Topology), link to docs and examples
|
|
- **CONTRIBUTING.md**: Already exists. Review for GitHub-specific guidance (fork workflow, PR template)
|
|
- **docs/**: Already comprehensive. Verify links work on GitHub rendering
|
|
- **Examples**: Ensure each example has a one-line description in its `Cargo.toml` and a comment block in `main.rs`
|
|
|
|
### 4.5 License and legal
|
|
|
|
- Verify workspace `license` field in root `Cargo.toml` is set correctly
|
|
- Add `LICENSE` file at repo root if not present
|
|
- Scan for any proprietary dependencies or hardcoded internal URLs
|
|
|
|
### 4.6 GitHub repository configuration
|
|
|
|
- Branch protection on `main`: require PR review, require CI to pass
|
|
- Issue templates: bug report, feature request
|
|
- PR template: checklist (tests pass, docs updated, etc.)
|
|
- Topics/tags: `rust`, `infrastructure-as-code`, `kubernetes`, `orchestration`, `bare-metal`
|
|
- Repository description: "Infrastructure orchestration framework. Declare what you want (Score), describe your infrastructure (Topology), let Harmony figure out how."
|
|
|
|
### 4.7 Gitea as internal mirror
|
|
|
|
- Set up Gitea to mirror from GitHub (pull mirror)
|
|
- Internal CI can continue running on Gitea for private/experimental branches
|
|
- Public contributions flow through GitHub
|
|
|
|
## Deliverables
|
|
|
|
- [ ] Git history cleaned, repo size <50MB
|
|
- [ ] Public GitHub repository created
|
|
- [ ] CI running on self-hosted runners with GitHub Actions
|
|
- [ ] Branch protection enabled
|
|
- [ ] README polished with quick-start guide
|
|
- [ ] Issue and PR templates created
|
|
- [ ] LICENSE file present
|
|
- [ ] Gitea configured as mirror
|