.github/README.md

   1 README.portable
   2 ===============
   3
   4 **NOTE: This repository is read-only and is used only to mirror the
   5 got-portable repository for CI purposes.**
   6
   7 This is the portable version of got[1] (Game of Trees), using autotools to
   8 provide the library checks required for GoT's dependencies.
   9
  10 The following operating systems are supported:
  11
  12 * FreeBSD
  13 * NetBSD
  14 * DragonFlyBSD
  15 * MacOS
  16 * Linux
  17
  18 DEPENDENCIES
  19 ============
  20
  21 Linux:
  22
  23 * `libncurses` (for tog(1))
  24 * `libbsd` (BSD's arc4random routines)
  25 * `libmd` (SHA256 routines)
  26 * `libuuid` (for UUID generation)
  27 * `libz` (for Z compression)
  28 * `pkg-config` (for searching libraries)
  29 * `bison` (for configuration file grammar)
  30
  31 FreeBSD:
  32
  33 * `automake`
  34 * `pkgconf`
  35 * `libevent` (for gotwebd)
  36
  37 NetBSD:
  38
  39 * `automake`
  40 * `libuuid`
  41 * `ncuresesw`
  42 * `libevent` (for gotwebd)
  43
  44 DragonFlyBSD:
  45
  46 * `automake`
  47 * `pkgconf`
  48 * `openssl`
  49 * `libevent` (for gotwebd)
  50
  51 Darwin (MacOS):
  52
  53 * `automake`
  54 * `bison`
  55 * `pkg-config`
  56 * `ncurses`
  57 * `openssl`
  58 * `ossp-uuid`
  59 * `libevent` (for gotwebd)
  60
  61 TESTS (REGRESS)
  62 ===============
  63
  64 To run the test suite:
  65
  66 ```
  67  $ make tests
  68 ```
  69
  70 Dependencies
  71 ============
  72
  73 * jot
  74 * ed
  75
  76 NOTE: For Linux, you must have the jot(1) command which is typically in the
  77 `athena-jot` package, or similar.
  78
  79 NOTE:  THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
  80        HELPERS ARE HARD-CODED INTO THE BINARIES.
  81
  82 INSTALLATION
  83 ============
  84
  85 ```
  86  $ ./autogen.sh
  87  $ ./configure && make
  88  $ sudo make install
  89 ```
  90
  91 BRANCHES + SUBMITTING PATCHES
  92 =============================
  93
  94 `got-portable` has two key branches:
  95
  96 * `main` which tracks got upstream untainted.
  97 * `portable` which provides the portable version of GoT based from code on `main`
  98
  99 Patches for portable code fixes should be based from the `portable` branch and
 100 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
 101
 102 Portable-specific patches should have a shortlog in the form of:
 103
 104 ```
 105 portable: AREA: description
 106 ```
 107
 108 Where `AREA` relates to the change in question (for example, `regress`,
 109 `libexec`, etc).  In some cases, this can be omitted if it's a generic change.
 110
 111 This helps to delineate `-portable` changes from upstream `got`.
 112
 113 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
 114 and FreeBSD.
 115
 116 SYNCING UPSTREAM CHANGES WITH PORTABLE
 117 ======================================
 118
 119 The `-portable` GoT repository uses the following workflow:
 120
 121 ```
 122                 Github (gh)               GoT (upstream)
 123                   ^                              ^
 124                   |                              |
 125                   |                              |
 126                   |                              |
 127                   |                              |
 128                   +--------> GoT-portable <------+
 129
 130 ```
 131
 132 Here, `got-portable` is a clone of the `-portable` repository, locally on
 133 disk.  There are two remotes set up within that repository, via `git-remote`:
 134
 135 * `upstream` -- which points to the official GoT repository;
 136 * `gh` -- which points to the mirrored `-portable` repository so that CI can
 137   be run for cross-platform/test purposes [3]
 138 * `origin` -- our cloned copy from `-portable`
 139
 140 Within the `-portable` repository are two key branches (there may be other
 141 topic branches which represent on-going work):
 142
 143 * `main` -- this is the branch that tracks (without modification) those
 144   changes from `upstream`.  This branch is continually reset to
 145   `upstream/main` whenever changes occur.
 146
 147 * `portable` -- this is the *default* branch of the `-portable` repository which
 148   contains portable-specific changes to make `GoT` compile across different
 149   OSes.
 150
 151 When updating `-portable` from upstream changes, the following actions happen:
 152
 153 1. Changes from `upstream` are fetched.  If there are no new changes, there's
 154    nothing else to do.
 155 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
 156 3. The difference between the local copy of `main` and `origin/main` is used
 157    to represent the set of commits which have *NOT* yet been merged to
 158    `-portable`.
 159 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
 160    branch to hold the to-be-cherry-picked commits from step 3.
 161 5. These commits are then cherry-picked to the `syncup` branch.
 162 6. If there's any conflicts, they must be resolved.
 163 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
 164 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
 165    `gh` for verification against CI.
 166 9. If that fails, fixes continue and pushed up to `gh` as required.
 167 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
 168
 169 These steps are encapsulated in a script within `-portable`.  [Link](../maintscripts/sync-upstream.sh)
 170
 171 RELEASING A NEW VERSION
 172 =======================
 173
 174 Release for `-portable` try and align as close to upstream GoT as much as
 175 possible, even on the same day where that can happen.  That being said,
 176 sometimes a release of `-portable` might happen outside of that cadence, where
 177 a `-portable`-specific issue needs addressing, for example.
 178
 179 Before creating a new release, check the version of GoT as found in
 180 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
 181
 182 ```
 183 GOT_PORTABLE_VER=0.75
 184
 185 ```
 186
 187 Here, the *to be released* version of `got-portable` will be `0.75`.
 188 Typically, this version is incremented directly after a release, such that
 189 there's no need to change this value.  The only exception would be if there
 190 were an out-of-band release to `-portable`.  In such cases, that would take
 191 the form:
 192
 193 ```
 194 0.75.1
 195 ```
 196
 197 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
 198 from the `0.75` version.
 199
 200 The variable `GOT_RELEASE` needs be changed to `yes` so that the
 201 GOT_PORTABLE_VER is asserted correctly.
 202
 203 Once the version is verified, the following should be run from the `portable`
 204 branch -- and the repository should not have any outstanding modifications to
 205 the source:
 206
 207 ```
 208 make clean ; ./autogen && ./configure && make distcheck
 209 ```
 210
 211 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
 212
 213 This can then be copied to the `got-www` repository and uploaded, along with
 214 changing a couple of HTML pages therein to represent the new released version.
 215 Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
 216
 217 Once all of that has been done, the repository should be tagged to indicate
 218 the release, hence:
 219
 220 ```
 221 git tag -a 0.75
 222 ```
 223
 224 This can then be pushed out to `gh` and `origin`.
 225
 226 After that point, the version of `GOT_PORTABLE_VER` in
 227 `util/got-portable-ver.sh` should be changed to the next version, and
 228 `GOT_RELEASE` should be setg back to `no`.
 229
 230 TODO
 231 ====
 232
 233 This port is incomplete in that only got(1) and tog(1) have been ported.
 234 gotweb has yet to be ported.
 235
 236 configure.ac should start defining AC_ENABLE arguments to allow for
 237 finer-grained control of where to search for includes/libraries, etc.
 238
 239 CONTACT
 240 =======
 241
 242 Thomas Adam <thomas@xteddy.org><br />
 243 thomas_adam (#gameoftrees on irc.libera.chat)
 244
 245 [1]  https://gameoftrees.org<br />
 246 [2]  https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees<br />
 247 [3]  https://github.com/ThomasAdam/got-portable