4 This is the portable version of got[1] (Game of Trees), using autotools to
5 provide the library checks required for GoT's dependencies.
7 The following operating systems are supported:
20 * `libncurses` (for tog(1))
21 * `libbsd` (BSD's arc4random routines)
22 * `libmd` (SHA256 routines)
23 * `libuuid` (for UUID generation)
24 * `libz` (for Z compression)
25 * `pkg-config` (for searching libraries)
26 * `bison` (for configuration file grammar)
27 * `libevent` (for gotwebd)
33 * `libevent` (for gotwebd)
40 * `libevent` (for gotwebd)
47 * `libevent` (for gotwebd)
57 * `libevent` (for gotwebd)
62 To run the test suite:
74 NOTE: For Linux, you must have the jot(1) command which is typically in the
75 `athena-jot` package, or similar.
77 NOTE: THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
78 HELPERS ARE HARD-CODED INTO THE BINARIES.
89 BRANCHES + SUBMITTING PATCHES
90 =============================
92 `got-portable` has two key branches:
94 * `main` which tracks got upstream untainted.
95 * `portable` which provides the portable version of GoT based from code on `main`
97 Patches for portable code fixes should be based from the `portable` branch and
98 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
100 Portable-specific patches should have a shortlog in the form of:
103 portable: AREA: description
106 Where `AREA` relates to the change in question (for example, `regress`,
107 `libexec`, etc). In some cases, this can be omitted if it's a generic change.
109 This helps to delineate `-portable` changes from upstream `got`.
111 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
114 SYNCING UPSTREAM CHANGES WITH PORTABLE
115 ======================================
117 The `-portable` GoT repository uses the following workflow:
120 Github (gh) GoT (upstream)
126 +--------> GoT-portable <------+
130 Here, `got-portable` is a clone of the `-portable` repository, locally on
131 disk. There are two remotes set up within that repository, via `git-remote`:
133 * `upstream` -- which points to the official GoT repository;
134 * `gh` -- which points to the mirrored `-portable` repository so that CI can
135 be run for cross-platform/test purposes [3]
136 * `origin` -- our cloned copy from `-portable`
138 Within the `-portable` repository are two key branches (there may be other
139 topic branches which represent on-going work):
141 * `main` -- this is the branch that tracks (without modification) those
142 changes from `upstream`. This branch is continually reset to
143 `upstream/main` whenever changes occur.
145 * `portable` -- this is the *default* branch of the `-portable` repository which
146 contains portable-specific changes to make `GoT` compile across different
149 When updating `-portable` from upstream changes, the following actions happen:
151 1. Changes from `upstream` are fetched. If there are no new changes, there's
153 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
154 3. The difference between the local copy of `main` and `origin/main` is used
155 to represent the set of commits which have *NOT* yet been merged to
157 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
158 branch to hold the to-be-cherry-picked commits from step 3.
159 5. These commits are then cherry-picked to the `syncup` branch.
160 6. If there's any conflicts, they must be resolved.
161 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
162 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
163 `gh` for verification against CI.
164 9. If that fails, fixes continue and pushed up to `gh` as required.
165 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
167 These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
169 RELEASING A NEW VERSION
170 =======================
172 Release for `-portable` try and align as close to upstream GoT as much as
173 possible, even on the same day where that can happen. That being said,
174 sometimes a release of `-portable` might happen outside of that cadence, where
175 a `-portable`-specific issue needs addressing, for example.
177 Before creating a new release, check the version of GoT as found in
178 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
181 GOT_PORTABLE_VER=0.75
185 Here, the *to be released* version of `got-portable` will be `0.75`.
186 Typically, this version is incremented directly after a release, such that
187 there's no need to change this value. The only exception would be if there
188 were an out-of-band release to `-portable`. In such cases, that would take
195 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
196 from the `0.75` version.
198 The variable `GOT_RELEASE` needs be changed to `yes` so that the
199 GOT_PORTABLE_VER is asserted correctly.
201 Once the version is verified, the following should be run from the `portable`
202 branch -- and the repository should not have any outstanding modifications to
206 make clean ; ./autogen && ./configure && make distcheck
209 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
211 This can then be copied to the `got-www` repository and uploaded, along with
212 changing a couple of HTML pages therein to represent the new released version.
213 Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
215 Once all of that has been done, the repository should be tagged to indicate
222 This can then be pushed out to `gh` and `origin`.
224 After that point, the version of `GOT_PORTABLE_VER` in
225 `util/got-portable-ver.sh` should be changed to the next version, and
226 `GOT_RELEASE` should be setg back to `no`.
231 * configure.ac should start defining AC_ENABLE arguments to allow for
232 finer-grained control of where to search for includes/libraries, etc.
233 * review the compat/ code. Some of those functions are probably picked up in
234 libbsd, so we should drop such implementations from compat/ where there's
235 overlap between libbsd and what's natively available.
240 Thomas Adam <thomas@xteddy.org><br />
241 thomas_adam (#gameoftrees on irc.libera.chat)
243 [1] https://gameoftrees.org<br />
244 [2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
245 [3] https://github.com/ThomasAdam/got-portable
