From 9c9477ae76ebb8f7ab4f1058e434d5e21fa3481c Mon Sep 17 00:00:00 2001 From: Thomas Adam Date: Mon, 13 Jul 2026 20:30:47 +0100 Subject: [PATCH] Tweak previous; include SYNCING.md --- SYNCING.md | 234 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 SYNCING.md diff --git a/SYNCING.md b/SYNCING.md new file mode 100644 index 000000000..9b710a463 --- /dev/null +++ b/SYNCING.md @@ -0,0 +1,234 @@ +# Preamble + +tmux portable is maintained from two repositories: + +* `tmux` is the portable repository. It contains the portability layer, + autotools build files, regression tests, documentation, and code needed for + platforms outside OpenBSD. +* `tmux-openbsd-cutover` is the OpenBSD tmux import repository. Its `master` + branch is the OpenBSD tmux history after the OpenBSD Git cutover. Portable + merges this branch when importing OpenBSD changes. + +To create the commits in the tmux-openbsd-cutover repo, the source repo is the +Github mirror of OpenBSD's src repo: + +```text +https://github.com/openbsd/src.git +``` + +The update automation filters the OpenBSD source tree to `usr.bin/tmux/`, +publishes that filtered history as `openbsd-git` in the cutover repository, +cherry-picks new filtered commits onto cutover `master`, then merges cutover +`master` into portable `master`. + +If you've never used git before, configure your identity before committing: + +```sh +git config [--global] user.name "Your name" +git config [--global] user.email "you@yourdomain.com" +``` + +# Repository layout + +The usual local layout is: + +```sh +cd /some/where/useful +git clone https://github.com/tmux/tmux.git tmux-portable +git clone https://github.com/ThomasAdam/tmux-obsd.git tmux-openbsd-cutover +``` + +The exact directory names do not matter, but the examples below use: + +```text +/path/to/tmux-portable +/path/to/tmux-openbsd-cutover +``` + +The cutover repository has three important branches: + +* `master` is the branch portable consumes. It should contain tmux source + only, not automation files. +* `openbsd-git` is the raw filtered OpenBSD tmux branch generated from + OpenBSD src `master`. +* `automation` is an orphan branch containing the GitHub Actions workflow. It + is separate so that workflow files are not merged into portable. + +# Adding the OpenBSD remote to portable + +In the portable repository, add the cutover repository as a remote: + +```sh +cd /path/to/tmux-portable +git remote add tmux-openbsd /path/to/tmux-openbsd-cutover +git config remote.tmux-openbsd.tagOpt --no-tags +``` + +If the remote already exists, update it instead: + +```sh +git remote set-url tmux-openbsd /path/to/tmux-openbsd-cutover +git config remote.tmux-openbsd.tagOpt --no-tags +``` + +Fetch the cutover master branch explicitly: + +```sh +git fetch --no-tags tmux-openbsd master:refs/remotes/tmux-openbsd/master +``` + +# Automated syncing + +The normal sync is performed by the GitHub Actions workflow in the +`automation` branch of the cutover repository. That workflow: + +1. Fetches or clones OpenBSD src using a blobless clone. +2. Filters `usr.bin/tmux/` into a local `tmux-openbsd` branch. +3. Updates `tmux-openbsd-cutover/openbsd-git`. +4. Cherry-picks new `openbsd-git` commits onto cutover `master`. +5. Merges cutover `master` into portable `master`. +6. Pushes the changed repositories. + +The workflow deliberately runs from the orphan `automation` branch but checks +out cutover `master` as the branch to update. This keeps `.github/` out of +cutover `master`, so portable does not import workflow files when it merges +OpenBSD changes. + +# Manual portable merge + +If the workflow fails while merging into portable, do the merge locally and +push the result. + +Start from an up-to-date portable master: + +```sh +cd /path/to/tmux-portable +git fetch origin +git checkout master +git pull --ff-only origin master +``` + +Fetch the cutover branch: + +```sh +git remote add tmux-openbsd /path/to/tmux-openbsd-cutover 2>/dev/null || true +git config remote.tmux-openbsd.tagOpt --no-tags +git fetch --no-tags tmux-openbsd master:refs/remotes/tmux-openbsd/master +``` + +Merge it: + +```sh +git merge --no-ff --log refs/remotes/tmux-openbsd/master +``` + +Resolve conflicts by deciding whether portable or OpenBSD owns the file. + +Useful commands: + +```sh +git checkout --ours path/to/file +git add path/to/file +``` + +This keeps the portable version of a conflicted file. + +```sh +git checkout --theirs path/to/file +git add path/to/file +``` + +This takes the OpenBSD/cutover version of a conflicted file. + +Before committing, inspect the result: + +```sh +git status +git diff --check +git diff --cached --stat +``` + +Then finish and publish: + +```sh +git commit +git push origin master +``` + +If the merge attempt is wrong, abort it: + +```sh +git merge --abort +``` + +After pushing a manually resolved merge, rerun the workflow. It should either +no-op or continue from the now-merged portable state. + +# Manual cutover update + +Normally this is handled by the workflow. If it must be done manually, update +`openbsd-git` in the cutover repository from a filtered OpenBSD src checkout, +then cherry-pick the new filtered commits onto cutover `master`. + +The important range is: + +```text +origin/openbsd-git..openbsd-git +``` + +where `origin/openbsd-git` is the previously published filtered OpenBSD tmux +branch and `openbsd-git` is the newly generated filtered branch. + +In the cutover repository: + +```sh +cd /path/to/tmux-openbsd-cutover +git checkout master +git cherry-pick origin/openbsd-git..openbsd-git +git push origin master openbsd-git +``` + +Do not put workflow files on cutover `master`; keep them on the orphan +`automation` branch. + +# Keeping an eye on libutil in OpenBSD + +A lot of the `compat/` code in tmux comes from OpenBSD libraries, especially +imsg. Sometimes APIs change in OpenBSD in ways that require corresponding +portable changes. It is worth checking periodically for relevant OpenBSD +libutil changes and syncing those files into `compat/` as appropriate. + +# Release tmux for next version + +1. Update and commit README and CHANGES. The former should be checked for + anything outdated and updated with a list of things that might break + upgrades and the latter should mention all the major changes since the last + version. +2. Make sure `configure.ac` has the new version number. +3. Tag with: + + ```sh + % git tag -a 2.X + ``` + + Where `2.X` is the next version. + + Push the tag out with: + + ```sh + % git push --tags + ``` + +4. Build the tarball with `make dist`. +5. Check the tarball. If it is good, go here to select the tag just pushed: + + ```text + https://github.com/tmux/tmux/tags + ``` + + Click "Add release notes", upload the tarball and add a link in the + description field to the CHANGES file. +6. Clone the tmux.github.io repository, and change the RELEASE version in the + Makefile. Commit it, and run `make` to replace `%%RELEASE%%`. Push the + result out. +7. Change version back to master in `configure.ac`.