mirror of
https://github.com/tmux/tmux.git
synced 2026-07-22 00:41:19 +00:00
Tweak previous; include SYNCING.md
This commit is contained in:
Thomas Adam
234
SYNCING.md
Normal file
234
SYNCING.md
Normal file
@@ -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`.
|
||||
Reference in New Issue
Block a user