mirror of
https://github.com/dredx/prole.git
synced 2026-09-23 11:03:59 +00:00
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>
This commit is contained in:
chrisfu
parent
3943d1b298
commit
decb9a5ad0
22
README.md
22
README.md
@ -310,6 +310,28 @@ Expect the architecture to continue being refined toward:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Upstream fork — knoe-db
|
||||||
|
|
||||||
|
This repository is an independent fork of the upstream knoe-db project:
|
||||||
|
|
||||||
|
```
|
||||||
|
git@git.knoe.dev:knoe-dev/knoe-db.git
|
||||||
|
```
|
||||||
|
|
||||||
|
Upstream changes are pulled into a dated review branch (`upstream/knoe-db/YYYYMMDD`) using the sync script, inspected, and selectively merged into `main`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Preview what the script will do
|
||||||
|
./scripts/sync_upstream_knoe_db.sh --dry-run
|
||||||
|
|
||||||
|
# Run the sync (requires a clean working tree)
|
||||||
|
./scripts/sync_upstream_knoe_db.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
See [`docs/upstream-knoe-db-sync.md`](docs/upstream-knoe-db-sync.md) for the full review-and-merge procedure.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Add the project license here.
|
Add the project license here.
|
||||||
|
|||||||
122
docs/upstream-knoe-db-sync.md
Normal file
122
docs/upstream-knoe-db-sync.md
Normal file
@ -0,0 +1,122 @@
|
|||||||
|
# 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
|
||||||
|
```
|
||||||
112
scripts/sync_upstream_knoe_db.sh
Executable file
112
scripts/sync_upstream_knoe_db.sh
Executable file
@ -0,0 +1,112 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# sync_upstream_knoe_db.sh — Pull upstream knoe-db changes into a review branch.
|
||||||
|
#
|
||||||
|
# Usage:
|
||||||
|
# ./scripts/sync_upstream_knoe_db.sh [--dry-run]
|
||||||
|
#
|
||||||
|
# What it does:
|
||||||
|
# 1. Ensures the 'upstream-knoe-db' remote points to git@git.knoe.dev:knoe-dev/knoe-db.git
|
||||||
|
# 2. Fetches the upstream default branch
|
||||||
|
# 3. Creates a timestamped branch upstream/knoe-db/YYYYMMDD from the fetch
|
||||||
|
# 4. Prints next steps for review and merge
|
||||||
|
#
|
||||||
|
# Run from the knoe-db/ subdirectory or the repo root (script auto-detects).
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
UPSTREAM_REMOTE="upstream-knoe-db"
|
||||||
|
UPSTREAM_URL="git@git.knoe.dev:knoe-dev/knoe-db.git"
|
||||||
|
UPSTREAM_BRANCH="main" # adjust if upstream uses a different default branch
|
||||||
|
DATE_TAG="$(date +%Y%m%d)"
|
||||||
|
REVIEW_BRANCH="upstream/knoe-db/${DATE_TAG}"
|
||||||
|
DRY_RUN=false
|
||||||
|
|
||||||
|
# ── argument parsing ──────────────────────────────────────────────────────────
|
||||||
|
for arg in "$@"; do
|
||||||
|
case "$arg" in
|
||||||
|
--dry-run) DRY_RUN=true ;;
|
||||||
|
*) echo "Unknown argument: $arg" >&2; exit 1 ;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
run() {
|
||||||
|
if $DRY_RUN; then
|
||||||
|
echo "[dry-run] $*"
|
||||||
|
else
|
||||||
|
"$@"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# ── locate the knoe-db git worktree ───────────────────────────────────────────
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||||
|
KNOE_DB_DIR="${REPO_ROOT}/knoe-db"
|
||||||
|
|
||||||
|
if [ ! -d "${KNOE_DB_DIR}/.git" ] && [ ! -f "${KNOE_DB_DIR}/.git" ]; then
|
||||||
|
# knoe-db may be a plain directory inside a mono-repo; operate from repo root
|
||||||
|
GIT_DIR="${REPO_ROOT}"
|
||||||
|
else
|
||||||
|
GIT_DIR="${KNOE_DB_DIR}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "==> Working in git repo: ${GIT_DIR}"
|
||||||
|
cd "${GIT_DIR}"
|
||||||
|
|
||||||
|
# ── ensure we are on a clean working tree ────────────────────────────────────
|
||||||
|
if ! $DRY_RUN; then
|
||||||
|
if ! git diff --quiet || ! git diff --cached --quiet; then
|
||||||
|
echo "ERROR: Working tree has uncommitted changes. Stash or commit before syncing." >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ── add / verify upstream remote ─────────────────────────────────────────────
|
||||||
|
if git remote get-url "${UPSTREAM_REMOTE}" &>/dev/null; then
|
||||||
|
CURRENT_URL="$(git remote get-url "${UPSTREAM_REMOTE}")"
|
||||||
|
if [ "${CURRENT_URL}" != "${UPSTREAM_URL}" ]; then
|
||||||
|
echo "==> Updating remote '${UPSTREAM_REMOTE}' URL to ${UPSTREAM_URL}"
|
||||||
|
run git remote set-url "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
|
||||||
|
else
|
||||||
|
echo "==> Remote '${UPSTREAM_REMOTE}' already set to ${UPSTREAM_URL}"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo "==> Adding remote '${UPSTREAM_REMOTE}' → ${UPSTREAM_URL}"
|
||||||
|
run git remote add "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ── fetch upstream ────────────────────────────────────────────────────────────
|
||||||
|
echo "==> Fetching ${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH} …"
|
||||||
|
run git fetch "${UPSTREAM_REMOTE}" "${UPSTREAM_BRANCH}"
|
||||||
|
|
||||||
|
# ── create review branch ──────────────────────────────────────────────────────
|
||||||
|
if git show-ref --verify --quiet "refs/heads/${REVIEW_BRANCH}"; then
|
||||||
|
echo "==> Branch '${REVIEW_BRANCH}' already exists — skipping creation."
|
||||||
|
echo " Delete it first if you want a fresh sync: git branch -D ${REVIEW_BRANCH}"
|
||||||
|
else
|
||||||
|
echo "==> Creating review branch '${REVIEW_BRANCH}' from ${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}"
|
||||||
|
run git checkout -b "${REVIEW_BRANCH}" "${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}"
|
||||||
|
run git checkout - # return to previous branch
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ── summary ───────────────────────────────────────────────────────────────────
|
||||||
|
echo ""
|
||||||
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
|
echo " Upstream sync complete."
|
||||||
|
echo ""
|
||||||
|
echo " Review branch : ${REVIEW_BRANCH}"
|
||||||
|
echo " Upstream : ${UPSTREAM_URL} (${UPSTREAM_BRANCH})"
|
||||||
|
echo ""
|
||||||
|
echo " Next steps:"
|
||||||
|
echo " 1. Inspect the incoming changes:"
|
||||||
|
echo " git log main..${REVIEW_BRANCH} --oneline"
|
||||||
|
echo " git diff main...${REVIEW_BRANCH} -- knoe-db/"
|
||||||
|
echo ""
|
||||||
|
echo " 2. Check out the review branch and resolve any conflicts:"
|
||||||
|
echo " git checkout ${REVIEW_BRANCH}"
|
||||||
|
echo ""
|
||||||
|
echo " 3. Merge (or cherry-pick) into main when satisfied:"
|
||||||
|
echo " git checkout main"
|
||||||
|
echo " git merge --no-ff ${REVIEW_BRANCH} -m 'chore(knoe-db): merge upstream ${DATE_TAG}'"
|
||||||
|
echo ""
|
||||||
|
echo " 4. Push and open a PR / MR for team review."
|
||||||
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
Loading…
Reference in New Issue
Block a user