mirror of
https://github.com/dredx/prole.git
synced 2026-09-23 10:13:58 +00:00
decb9a5ad0
Add scripts/sync_upstream_knoe_db.sh — idempotent script that registers the upstream-knoe-db remote (git@git.knoe.dev:knoe-dev/knoe-db.git), fetches upstream main, and creates a dated review branch upstream/knoe-db/YYYYMMDD. Supports --dry-run; returns to previous branch automatically. Add docs/upstream-knoe-db-sync.md — step-by-step procedure covering quick start, clean-tree requirement, diff/review, merge-to-main, PR workflow, branch cleanup, and how to change the upstream branch name. Update README.md: add 'Upstream fork — knoe-db' section with quick-start commands and link to the sync procedure doc. Co-authored-by: Junie <junie@jetbrains.com>
123 lines
3.0 KiB
Markdown
123 lines
3.0 KiB
Markdown
# Upstream knoe-db Sync Procedure
|
|
|
|
This repo is an independent fork of the upstream knoe-db project hosted at:
|
|
|
|
```
|
|
git@git.knoe.dev:knoe-dev/knoe-db.git
|
|
```
|
|
|
|
The script `scripts/sync_upstream_knoe_db.sh` automates fetching upstream changes
|
|
and staging them in a dedicated review branch so they can be inspected and selectively
|
|
merged into `main`.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
chmod +x scripts/sync_upstream_knoe_db.sh
|
|
./scripts/sync_upstream_knoe_db.sh
|
|
```
|
|
|
|
Use `--dry-run` to preview what the script would do without touching the repo:
|
|
|
|
```bash
|
|
./scripts/sync_upstream_knoe_db.sh --dry-run
|
|
```
|
|
|
|
> **Requires a clean working tree.** The script will exit with an error if
|
|
> `git diff` or `git diff --cached` reports any changes. Stash or commit
|
|
> your work first:
|
|
>
|
|
> ```bash
|
|
> git stash # or: git add -A && git commit -m "wip: stash before upstream sync"
|
|
> ./scripts/sync_upstream_knoe_db.sh
|
|
> git stash pop # restore your work afterwards
|
|
> ```
|
|
>
|
|
> If you only want to inspect what the script would do without touching the
|
|
> repo at all, `--dry-run` bypasses the clean-tree check.
|
|
|
|
---
|
|
|
|
## What the script does
|
|
|
|
1. **Registers the upstream remote** `upstream-knoe-db` (idempotent — safe to re-run).
|
|
2. **Fetches** `upstream-knoe-db/main` (no local branches are modified).
|
|
3. **Creates a timestamped review branch** `upstream/knoe-db/YYYYMMDD` pointing at the
|
|
tip of the upstream fetch.
|
|
4. **Returns you to your previous branch** automatically.
|
|
5. **Prints next steps** with ready-to-paste git commands.
|
|
|
|
---
|
|
|
|
## Review and merge workflow
|
|
|
|
### 1. See what changed
|
|
|
|
```bash
|
|
# Commits in upstream not yet in main
|
|
git log main..upstream/knoe-db/$(date +%Y%m%d) --oneline
|
|
|
|
# Full diff scoped to the knoe-db/ directory
|
|
git diff main...upstream/knoe-db/$(date +%Y%m%d) -- knoe-db/
|
|
```
|
|
|
|
### 2. Check out the review branch
|
|
|
|
```bash
|
|
git checkout upstream/knoe-db/$(date +%Y%m%d)
|
|
```
|
|
|
|
Browse, test, or cherry-pick individual commits as needed.
|
|
|
|
### 3. Merge into main
|
|
|
|
When the changes look good:
|
|
|
|
```bash
|
|
git checkout main
|
|
git merge --no-ff upstream/knoe-db/$(date +%Y%m%d) \
|
|
-m "chore(knoe-db): merge upstream $(date +%Y%m%d)"
|
|
```
|
|
|
|
Resolve any conflicts, then:
|
|
|
|
```bash
|
|
git push origin main
|
|
```
|
|
|
|
### 4. Open a PR / MR (recommended)
|
|
|
|
Push the review branch and open a pull request so the team can review before
|
|
merging into `main`:
|
|
|
|
```bash
|
|
git push origin upstream/knoe-db/$(date +%Y%m%d)
|
|
# then open a PR targeting main
|
|
```
|
|
|
|
---
|
|
|
|
## Keeping the upstream remote up to date
|
|
|
|
The script is idempotent — running it again on a later date will fetch the latest
|
|
upstream state and create a new dated branch (e.g. `upstream/knoe-db/20260601`).
|
|
Old review branches can be deleted once merged:
|
|
|
|
```bash
|
|
git branch -d upstream/knoe-db/20260523
|
|
git push origin --delete upstream/knoe-db/20260523
|
|
```
|
|
|
|
---
|
|
|
|
## Adjusting the upstream branch name
|
|
|
|
If the upstream project uses a branch other than `main` (e.g. `master` or `develop`),
|
|
edit the `UPSTREAM_BRANCH` variable near the top of `scripts/sync_upstream_knoe_db.sh`:
|
|
|
|
```bash
|
|
UPSTREAM_BRANCH="master" # ← change as needed
|
|
```
|