mirror of https://github.com/dredx/prole.git synced 2026-09-23 09:13:58 +00:00

chrisfu decb9a5ad0 feat(scripts): upstream knoe-db sync tooling and docs

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>

2026-05-23 21:31:48 -07:00

3.0 KiB

Raw Permalink Blame History

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

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:

./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:
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

Registers the upstream remote upstream-knoe-db (idempotent — safe to re-run).
Fetches upstream-knoe-db/main (no local branches are modified).
Creates a timestamped review branch upstream/knoe-db/YYYYMMDD pointing at the tip of the upstream fetch.
Returns you to your previous branch automatically.
Prints next steps with ready-to-paste git commands.

Review and merge workflow

1. See what changed

# 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

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:

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:

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:

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:

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:

UPSTREAM_BRANCH="master"   # ← change as needed

3.0 KiB Raw Permalink Blame History