d69ce1c388
Add check-upstream.sh, generated status artifacts, merge guide, and a scheduled Forgejo job to refresh upstream sync visibility. Co-authored-by: Cursor <cursoragent@cursor.com>
102 lines
2.6 KiB
Markdown
102 lines
2.6 KiB
Markdown
# Syncing with upstream (komikku-app/komikku)
|
|
|
|
This Forgejo fork tracks [komikku-app/komikku](https://github.com/komikku-app/komikku) on GitHub.
|
|
|
|
| Remote | URL | Branch |
|
|
|--------|-----|--------|
|
|
| `origin` | Your Forgejo instance | `main` |
|
|
| `upstream` | `https://github.com/komikku-app/komikku.git` | `master` |
|
|
|
|
Current divergence is recorded in [UPSTREAM_STATUS.md](../UPSTREAM_STATUS.md) (updated weekly by Forgejo Actions).
|
|
|
|
## Quick check
|
|
|
|
```sh
|
|
./scripts/check-upstream.sh
|
|
```
|
|
|
|
Write refreshed status files:
|
|
|
|
```sh
|
|
./scripts/check-upstream.sh --write
|
|
```
|
|
|
|
JSON only:
|
|
|
|
```sh
|
|
./scripts/check-upstream.sh --json
|
|
```
|
|
|
|
## One-time setup
|
|
|
|
If `upstream` is missing:
|
|
|
|
```sh
|
|
git remote add upstream https://github.com/komikku-app/komikku.git
|
|
git fetch upstream
|
|
```
|
|
|
|
## Merge upstream into the fork
|
|
|
|
1. Commit or stash local work.
|
|
2. Update refs and inspect divergence:
|
|
|
|
```sh
|
|
git fetch upstream
|
|
git fetch origin
|
|
./scripts/check-upstream.sh
|
|
git log --oneline main..upstream/master # incoming upstream commits
|
|
git log --oneline upstream/master..main # fork-only commits
|
|
```
|
|
|
|
3. Merge (recommended for shared `main`):
|
|
|
|
```sh
|
|
git checkout main
|
|
git merge upstream/master
|
|
```
|
|
|
|
Resolve conflicts, then:
|
|
|
|
```sh
|
|
git add -A
|
|
git commit # if merge was not auto-committed
|
|
```
|
|
|
|
4. Push to Forgejo (never force-push `main` unless you intend to):
|
|
|
|
```sh
|
|
git push origin main
|
|
```
|
|
|
|
## Expected conflict areas
|
|
|
|
Merges often conflict where the fork diverged from upstream:
|
|
|
|
- `.github/workflows/*.yml` — upstream GitHub Actions vs fork Forgejo release workflow
|
|
- `README.md` — fork-specific Forgejo / Obtainium notes
|
|
- `i18n-kmk/.../de/strings.xml` — parallel translation edits
|
|
- `data/src/main/sqldelight/tachiyomi/migrations/46.sqm` — schema migration numbering
|
|
|
|
Keep fork-specific CI in `.forgejo/workflows/` and upstream CI in `.github/workflows/`; resolve workflow conflicts by keeping both sides where possible.
|
|
|
|
## Rebase alternative
|
|
|
|
For a linear history on a private branch (not `main`):
|
|
|
|
```sh
|
|
git checkout -b sync/upstream-$(date +%Y%m%d)
|
|
git rebase upstream/master
|
|
```
|
|
|
|
Then test, merge the sync branch into `main`, and push.
|
|
|
|
## Automation
|
|
|
|
Workflow: [`.forgejo/workflows/upstream_status.yml`](../.forgejo/workflows/upstream_status.yml)
|
|
|
|
- Runs every Monday 06:00 UTC and on manual dispatch
|
|
- Updates `UPSTREAM_STATUS.md` and `docs/upstream-status.json`
|
|
- Opens or updates a single `upstream-sync` issue when more than 10 commits behind
|
|
|
|
On a private Forgejo host, dynamic shields.io badges cannot read your repo; use `UPSTREAM_STATUS.md` or the JSON file instead.
|