keep cross-site forks synchronized

UPSTREAM.md

Upstream Parity

This repo was "forked" from the source on source site.

To facilitate tracking the upstream changes, the following git config modifications were made:

1. Added a git remote called "upstream" which points to the source repo,
2. Added a local branch called "upstream/main" to track the "upstream" remote's "main" branch
3. Added a local branch called "merge/upstream-main" which is an intermediary branch containing merge conflict resolutions when bringing in changes from upstream.

To pull changes from the upstream project, run:

  git checkout upstream/main
  git pull
  git push origin
  git pull upstream --tags --force
  git push origin --tags --force
  git checkout merge/upstream-main
  git merge main
  git merge upstream/main
  # See "Merge Strategy" instructions below
  # ...resolve merge conflicts...
  git add --all
  git commit --amend --no-edit
  # Create new upstream-## tag (NOTE: upstream-00 must be created manually)
  git tag $(git tag --sort v:refname -l 'upstream-*' | tail -n 1 | awk '{ gsub(/upstream-/, ""); printf "upstream-%02d\n", $1 + 1 }')
  git push
  git push --tags

Merge Strategy

Where conflicts arise, compare OUR changes since last upstream merge to THEIR changes since last upstream merge:

• Diff of OUR changes since previous merge (replacing upstream-{##} with the previous merge tag number):
  • [bitbucket url]/compare/diff?sourceBranch=main&targetBranch=tags/upstream-{##}
• Diff of THEIR changes since previous merge (replacing upstream-{##} with the previous merge tag number):
  • [bitbucket url]/compare/diff?sourceBranch=tags/nightly&targetBranch=tags/upstream-{##}

NOTE: Always discard lockfile changes. Complete the merge, then see "Package Changes" below for package dependency update strategy.

Package Changes

Ensure updates to the python pyproject.toml and npm package.json packages are appropriately made. Oftentimes OUR updates will incorrectly clobber THEIR updates, resulting in outdated package versions persisting across the upstream merge. Don't let this happen.

1. Compare THEIR pyproject.toml and package.json diffs to OUR diffs (see above). Whichever has the latest package version shall prevail.
2. Discard lockfile changes if merge conflicts exist. Update python uv install and npm npm install packages.