README.portable

   1 README.portable
   2 ===============
   3
   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.
   6
   7 The following operating systems are supported:
   8
   9 * FreeBSD
  10 * NetBSD
  11 * DragonFlyBSD
  12 * MacOS
  13 * Linux
  14
  15 DEPENDENCIES
  16 ============
  17
  18 Linux:
  19
  20 * `libncurses` (for tog(1))
  21 * `libmd` (BSD's digest routines)
  22 * `libbsd` (BSD's arc4random routines)
  23 * `libcrypto` (often via 'libssl-dev' for SHA1 routines)
  24 * `libuuid` (for UUID generation)
  25 * `libz` (for Z compression)
  26 * `pkg-config` (for searching libraries)
  27 * `bison` (for configuration file grammar)
  28 * `libevent` (for gotwebd)
  29
  30 FreeBSD:
  31
  32 * `automake`
  33 * `pkgconf`
  34 * `GNU coreutils` (for running tests)
  35 * `libevent` (for gotwebd)
  36
  37 NetBSD:
  38
  39 * `automake`
  40 * `libuuid`
  41 * `ncuresesw`
  42 * `GNU coreutils` (for running tests)
  43 * `libevent` (for gotwebd)
  44
  45 DragonFlyBSD:
  46
  47 * `automake`
  48 * `pkgconf`
  49 * `openssl`
  50 * `GNU coreutils` (for running tests)
  51 * `libevent` (for gotwebd)
  52
  53 Darwin (MacOS):
  54
  55 * `automake`
  56 * `bison`
  57 * `pkg-config`
  58 * `ncurses`
  59 * `openssl`
  60 * `ossp-uuid`
  61 * `GNU coreutils` (for running tests)
  62 * `libevent` (for gotwebd)
  63
  64 TESTS (REGRESS)
  65 ===============
  66
  67 To run the test suite:
  68
  69 ```
  70  $ make tests
  71 ```
  72
  73 NOTE: For Linux, you must have the jot(1) command which is typically in the
  74 `athena-jot` package, or similar.  For non-linux systems (as mentioned above),
  75 GNU coreutils needs to be installed.
  76
  77 NOTE:  THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
  78        HELPERS ARE HARD-CODED INTO THE BINARIES.
  79
  80 INSTALLATION
  81 ============
  82
  83 ```
  84  $ ./autogen.sh
  85  $ ./configure && make
  86  $ sudo make install
  87 ```
  88
  89 BRANCHES + SUBMITTING PATCHES
  90 =============================
  91
  92 `got-portable` has two key branches:
  93
  94 * `main` which tracks got upstream untainted.
  95 * `linux` which provides the portable version of GoT based from code on `main`
  96
  97 Patches for portable code fixes should be based from the `linux` branch and
  98 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
  99
 100 Portable-specific patches should have a shortlog in the form of:
 101
 102 ```
 103 portable: AREA: description
 104 ```
 105
 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.
 108
 109 This helps to delineate `-portable` changes from upstream `got`.
 110
 111 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
 112 and FreeBSD.
 113
 114 SYNCING UPSTREAM CHANGES WITH PORTABLE
 115 ======================================
 116
 117 The `-portable` GoT repository uses the following workflow:
 118
 119 ```
 120                 Github (gh)               GoT (upstream)
 121                   ^                              ^
 122                   |                              |
 123                   |                              |
 124                   |                              |
 125                   |                              |
 126                   +--------> GoT-portable <------+
 127
 128 ```
 129
 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`:
 132
 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`
 137
 138 Within the `-portable` repository are two key branches (there may be other
 139 topic branches which represent on-going work):
 140
 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.
 144
 145 * `linux` -- this is the *default* branch of the `-portable` repository which
 146   contains portable-specific changes to make `GoT` compile across different
 147   OSes.
 148
 149 When updating `-portable` from upstream changes, the following actions happen:
 150
 151 1. Changes from `upstream` are fetched.  If there are no new changes, there's
 152    nothing else to do.
 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
 156    `-portable`.
 157 4. A topic-branch called `syncup` is created from the HEAD of the `linux`
 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 `linux` 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 `linux` branches can be merged to `origin`.
 166
 167 These steps are encapsulated in a script within `-portable`.  [Link](../maintscripts/sync-upstream.sh)
 168
 169 RELEASING A NEW VERSION
 170 =======================
 171
 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.
 176
 177 Before creating a new release, check the version of GoT as found in
 178 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
 179
 180 ```
 181 GOT_PORTABLE_VER=0.75
 182
 183 ```
 184
 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
 189 the form:
 190
 191 ```
 192 0.75.1
 193 ```
 194
 195 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
 196 from the `0.75` version.
 197
 198 The variable `GOT_RELEASE` needs be changed to `yes` so that the
 199 GOT_PORTABLE_VER is asserted correctly.
 200
 201 Once the version is verified, the following should be run from the `linux`
 202 branch -- and the repository should not have any outstanding modifications to
 203 the source:
 204
 205 ```
 206 make clean ; ./autogen && ./configure && make distcheck
 207 ```
 208
 209 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
 210
 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.
 214
 215 Once all of that has been done, the repository should be tagged to indicate
 216 the release, hence:
 217
 218 ```
 219 git tag -a 0.75
 220 ```
 221
 222 This can then be pushed out to `gh` and `origin`.
 223
 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`.
 227
 228 TODO
 229 ====
 230
 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
 234 CONTACT
 235 =======
 236
 237 Thomas Adam <thomas@xteddy.org><br />
 238 thomas_adam (#gameoftrees on irc.libera.chat)
 239
 240 [1]  https://gameoftrees.org<br />
 241 [2]  https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
 242 [3]  https://github.com/ThomasAdam/got-portable