# 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/tmux/tmux-openbsd-cutover.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 published cutover repository as a remote.
This works regardless of which branch is checked out in a local cutover clone:

```sh
cd /path/to/tmux-portable
git remote add tmux-openbsd https://github.com/tmux/tmux-openbsd-cutover.git
git config remote.tmux-openbsd.tagOpt --no-tags
```

If the remote already exists, update it instead:

```sh
git remote set-url tmux-openbsd https://github.com/tmux/tmux-openbsd-cutover.git
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
```

To merge unpublished changes from a local cutover clone instead, first ensure
it has an up-to-date local `master` branch. A normal clone may check out
`automation` and have only `origin/master`; fetching `master` from that clone
will then fail with `couldn't find remote ref master`.

With a clean cutover working tree:

```sh
cd /path/to/tmux-openbsd-cutover
git fetch --no-tags origin
git switch master
git merge --ff-only origin/master
```

`git switch master` creates a tracking branch from `origin/master` if there is
no local `master` yet. If the fast-forward fails, reconcile the local cutover
changes before continuing; do not reset them away.

Then, in portable, point the remote at that clone and fetch its local `master`:

```sh
cd /path/to/tmux-portable
git remote set-url tmux-openbsd /path/to/tmux-openbsd-cutover
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 with a clean working tree and an up-to-date portable master. If a merge
is already in progress, skip to resolving conflicts, or abort it before
starting again:

```sh
cd /path/to/tmux-portable
git fetch origin
git checkout master
git pull --ff-only origin master
```

Fetch the published cutover branch. Update an existing remote as well, since
it may point at a local clone without a `master` branch or with a stale one:

```sh
if git remote get-url tmux-openbsd >/dev/null 2>&1; then
    git remote set-url tmux-openbsd https://github.com/tmux/tmux-openbsd-cutover.git
else
    git remote add tmux-openbsd https://github.com/tmux/tmux-openbsd-cutover.git
fi
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
```

If merging a local cutover branch instead, use the local-clone preparation
and fetch commands above in place of this fetch block.

When the merge reports conflicts, it leaves the merge in progress. List the
unresolved files, edit the conflict markers to combine the required portable
and OpenBSD changes, then stage each resolved file:

```sh
git diff --name-only --diff-filter=U
git diff -- path/to/file
git add path/to/file
```

For files that should come entirely from one side, decide whether portable or
OpenBSD owns the file before using the commands below. They replace the whole
file, including changes outside the conflicting hunks.

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.

For a modify/delete conflict, the side that deleted the file has no version
to check out. For example, portable generates `Makefile` using autotools and
does not track OpenBSD's `Makefile`. If Git reports that `Makefile` was deleted
in HEAD and modified in cutover, keep the portable deletion with:

```sh
git rm -- Makefile
```

This removes the OpenBSD file left by the merge; regenerate the portable
`Makefile` with your usual configure command before building. Use this only
for the unmerged OpenBSD file, not an existing generated build file.

Before committing, inspect the result:

```sh
git status
git diff --check
git diff --cached --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`.