commit - 0dd633fe8a85c7540c5d24085f24ac9ea2e456af
commit + 585fb4308db8e9dd168f98d07dd6a3af76f6a415
blob - 3442bd2d6e90e3dcff583321df4ea7e84fc5a0b3
blob + afa72ab41b82100ff3473ac243f7e200767dd2ca
--- .github/README.md
+++ .github/README.md
The read-only Github repository also runs CI checks using Cirrus-CI on Linux
and FreeBSD.
+SYNCING UPSTREAM CHANGES WITH PORTABLE
+======================================
+
+The `-portable` GoT repository uses the following workflow:
+
+```
+ Github (gh) GoT (upstream)
+ ^ ^
+ | |
+ | |
+ | |
+ | |
+ +--------> GoT-portable <------+
+
+```
+
+Here, `got-portable` is a clone of the `-portable` repository, locally on
+disk. There are two remotes set up within that repository, via `git-remote`:
+
+* `upstream` -- which points to the official GoT repository;
+* `gh` -- which points to the mirrored `-portable` repository so that CI can
+ be run for cross-platform/test purposes [3]
+* `origin` -- our cloned copy from `-portable`
+
+Within the `-portable` repository are two key branches (there may be other
+topic branches which represent on-going work):
+
+* `main` -- this is the branch that tracks (without modification) those
+ changes from `upstream`. This branch is continually reset to
+ `upstream/main` whenever changes occur.
+
+* `linux` -- this is the *default* branch of the `-portable` repository which
+ contains portable-specific changes to make `GoT` compile across different
+ OSes.
+
+When updating `-portable` from upstream changes, the following actions happen:
+
+1. Changes from `upstream` are fetched. If there are no new changes, there's
+ nothing else to do.
+2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
+3. The difference between the local copy of `main` and `origin/main` is used
+ to represent the set of commits which have *NOT* yet been merged to
+ `-portable`.
+4. A topic-branch called `syncup` is created from the HEAD of the `linux`
+ branch to hold the to-be-cherry-picked commits from step 3.
+5. These commits are then cherry-picked to the `syncup` branch.
+6. If there's any conflicts, they must be resolved.
+7. Once done, a sanity build is done in-situ to check there's nothing amiss.
+8. If that succeeds, the `syncup` branch is merged to `linux` and pushed to
+ `gh` for verification against CI.
+9. If that fails, fixes continue and pushed up to `gh` as required.
+10. Once happy, both the `main` and `linux` branches can be merged to `origin`.
+
+These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
+
TODO
====
CONTACT
=======
-Thomas Adam <thomas@xteddy.org>
+Thomas Adam <thomas@xteddy.org><br />
thomas_adam (#gameoftrees on irc.libera.chat)
-[1] https://gameoftrees.org
-[2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
+[1] https://gameoftrees.org<br />
+[2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees<br />
+[3] https://github.com/ThomasAdam/got-portable
blob - 7cf7c790e8b73349d40fae822a66ceeba22f6535
blob + 5e94ff506948ca5730c38c2a95452d9534ed02ef
--- README.portable
+++ README.portable
The read-only Github repository also runs CI checks using Cirrus-CI on Linux
and FreeBSD.
+SYNCING UPSTREAM CHANGES WITH PORTABLE
+======================================
+
+The `-portable` GoT repository uses the following workflow:
+
+```
+ Github (gh) GoT (upstream)
+ ^ ^
+ | |
+ | |
+ | |
+ | |
+ +--------> GoT-portable <------+
+
+```
+
+Here, `got-portable` is a clone of the `-portable` repository, locally on
+disk. There are two remotes set up within that repository, via `git-remote`:
+
+* `upstream` -- which points to the official GoT repository;
+* `gh` -- which points to the mirrored `-portable` repository so that CI can
+ be run for cross-platform/test purposes [3]
+* `origin` -- our cloned copy from `-portable`
+
+Within the `-portable` repository are two key branches (there may be other
+topic branches which represent on-going work):
+
+* `main` -- this is the branch that tracks (without modification) those
+ changes from `upstream`. This branch is continually reset to
+ `upstream/main` whenever changes occur.
+
+* `linux` -- this is the *default* branch of the `-portable` repository which
+ contains portable-specific changes to make `GoT` compile across different
+ OSes.
+
+When updating `-portable` from upstream changes, the following actions happen:
+
+1. Changes from `upstream` are fetched. If there are no new changes, there's
+ nothing else to do.
+2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
+3. The difference between the local copy of `main` and `origin/main` is used
+ to represent the set of commits which have *NOT* yet been merged to
+ `-portable`.
+4. A topic-branch called `syncup` is created from the HEAD of the `linux`
+ branch to hold the to-be-cherry-picked commits from step 3.
+5. These commits are then cherry-picked to the `syncup` branch.
+6. If there's any conflicts, they must be resolved.
+7. Once done, a sanity build is done in-situ to check there's nothing amiss.
+8. If that succeeds, the `syncup` branch is merged to `linux` and pushed to
+ `gh` for verification against CI.
+9. If that fails, fixes continue and pushed up to `gh` as required.
+10. Once happy, both the `main` and `linux` branches can be merged to `origin`.
+
+These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
+
TODO
====
CONTACT
=======
-Thomas Adam <thomas@xteddy.org>
+Thomas Adam <thomas@xteddy.org><br />
thomas_adam (#gameoftrees on irc.libera.chat)
-[1] https://gameoftrees.org
+[1] https://gameoftrees.org<br />
[2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
+[3] https://github.com/ThomasAdam/got-portable
