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 Note that the names of these libraries are indicative only; the names might
  19 vary.
  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 * `libevent` (for gotwebd)
  31 * `libtls` (may be known as `libretls`)
  32
  33 FreeBSD:
  34
  35 * `automake`
  36 * `pkgconf`
  37 * `libretls`
  38 * `libevent` (for gotwebd)
  39
  40 NetBSD:
  41
  42 * `automake`
  43 * `libuuid`
  44 * `ncuresesw`
  45 * `libevent` (for gotwebd)
  46 * `libretls`
  47
  48 DragonFlyBSD:
  49
  50 * `automake`
  51 * `pkgconf`
  52 * `openssl`
  53 * `libevent` (for gotwebd)
  54 * `libretls`
  55
  56 Darwin (MacOS):
  57
  58 * `automake`
  59 * `bison`
  60 * `pkg-config`
  61 * `ncurses`
  62 * `openssl`
  63 * `ossp-uuid`
  64 * `libevent` (for gotwebd)
  65 * `libretls`
  66
  67 TESTS (REGRESS)
  68 ===============
  69
  70 To run the test suite:
  71
  72 ```
  73  $ make tests
  74 ```
  75
  76 Dependencies
  77 ============
  78
  79 * ed
  80
  81 NOTE:  THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
  82        HELPERS ARE HARD-CODED INTO THE BINARIES.
  83
  84 INSTALLATION
  85 ============
  86
  87 ```
  88  $ ./autogen.sh
  89  $ ./configure && make
  90  $ sudo make install
  91 ```
  92
  93 INSTALLING AND PACKAGING GITWRAPPER
  94 ===================================
  95
  96 The gotd server has an optional companion tool called gitwrapper.
  97
  98 A gotd server can be used without gitwrapper in the following cases:
  99
 100 1) The Git client's user account has gotsh configured as its login shell.
 101
 102 2) The Git client's user account sees gotsh installed under the names
 103    git-receive-pack and git-upload-pack, and these appear in $PATH before
 104    the corresponding Git binaries if Git is also installed. Setting up the
 105    user's $PATH in this way can require the use of SetEnv in sshd_config.
 106
 107 The above cases can be too restrictive. For example, users who have regular
 108 shell access to the system may expect to be able to serve Git repositories
 109 from their home directories while also accessing repositories served by gotd.
 110
 111 Once gitwrapper has been installed correctly it provides an out-of-the box
 112 experience where both gotd and Git "just work".
 113 However, this will require coordination with the system's Git installation
 114 and/or distribution package because the names of two specific Git programs
 115 will be overlapping: git-upload-pack and git-receive-pack
 116
 117 If the gitwrapper tool will be used then it must replace git-receive-pack
 118 and git-upload-pack in /usr/bin. This is usually achieved by replacing the
 119 regular Git binaries in /usr/bin with symlinks to gitwrapper:
 120
 121 ```
 122 -rwxr-xr-x 1 root root 1019928 Aug 24 00:16 /usr/bin/gitwrapper
 123 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-receive-pack -> gitwrapper
 124 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-upload-pack -> gitwrapper
 125 ```
 126
 127 The Git binaries remain available in Git's libexec directory, which is set
 128 when Git gets compiled. On Debian it defaults to /usr/lib/git-core.
 129 This same path must be given to Got's configure script at build time to
 130 allow gitwrapper to find Git's binaries:
 131
 132 ```
 133   ./configure --with-gitwrapper-git-libexec-path=/usr/lib/git-core
 134 ```
 135
 136 Once gitwrapper is found in /usr/bin under the names git-receive-pack and
 137 git-upload-pack, any Git repositories listed in /etc/gotd.conf will be
 138 automatically served by gotd, and any Git repositories not listed in
 139 /etc/gotd.conf will be automatically served by regular Git's git-upload-pack
 140 and git-receive-pack. The client's login shell or $PATH no longer matter,
 141 and a peaceful co-existence of gotd and Git is possible.
 142
 143 We recommend that distribution packagers take appropriate steps to package
 144 gitwrapper as a required dependency of gotd. It is also possible to install
 145 gitwrapper without installing gotd. As long as /etc/gotd.conf does not exist
 146 or no repositories are listed in /etc/gotd.conf there will be no visible
 147 change in run-time behaviour for Git users since gitwrapper will simply run
 148 the standard Git tools.
 149 In the OpenBSD ports tree both the regular git package and the gotd package
 150 are depending on gitwrapper, and the git package no longer installs the
 151 git-receive-pack and git-upload-pack programs in /usr/local/bin.
 152
 153 BRANCHES + SUBMITTING PATCHES
 154 =============================
 155
 156 `got-portable` has two key branches:
 157
 158 * `main` which tracks got upstream untainted.
 159 * `portable` which provides the portable version of GoT based from code on `main`
 160
 161 Patches for portable code fixes should be based from the `portable` branch and
 162 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
 163
 164 Portable-specific patches should have a shortlog in the form of:
 165
 166 ```
 167 portable: AREA: description
 168 ```
 169
 170 Where `AREA` relates to the change in question (for example, `regress`,
 171 `libexec`, etc).  In some cases, this can be omitted if it's a generic change.
 172
 173 This helps to delineate `-portable` changes from upstream `got`.
 174
 175 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
 176 and FreeBSD.
 177
 178 SYNCING UPSTREAM CHANGES WITH PORTABLE
 179 ======================================
 180
 181 The `-portable` GoT repository uses the following workflow:
 182
 183 ```
 184                 Github (gh)               GoT (upstream)
 185                   ^                              ^
 186                   |                              |
 187                   |                              |
 188                   |                              |
 189                   |                              |
 190                   +--------> GoT-portable <------+
 191
 192 ```
 193
 194 Here, `got-portable` is a clone of the `-portable` repository, locally on
 195 disk.  There are two remotes set up within that repository, via `git-remote`:
 196
 197 * `upstream` -- which points to the official GoT repository;
 198 * `gh` -- which points to the mirrored `-portable` repository so that CI can
 199   be run for cross-platform/test purposes [3]
 200 * `origin` -- our cloned copy from `-portable`
 201
 202 Within the `-portable` repository are two key branches (there may be other
 203 topic branches which represent on-going work):
 204
 205 * `main` -- this is the branch that tracks (without modification) those
 206   changes from `upstream`.  This branch is continually reset to
 207   `upstream/main` whenever changes occur.
 208
 209 * `portable` -- this is the *default* branch of the `-portable` repository which
 210   contains portable-specific changes to make `GoT` compile across different
 211   OSes.
 212
 213 When updating `-portable` from upstream changes, the following actions happen:
 214
 215 1. Changes from `upstream` are fetched.  If there are no new changes, there's
 216    nothing else to do.
 217 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
 218 3. The difference between the local copy of `main` and `origin/main` is used
 219    to represent the set of commits which have *NOT* yet been merged to
 220    `-portable`.
 221 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
 222    branch to hold the to-be-cherry-picked commits from step 3.
 223 5. These commits are then cherry-picked to the `syncup` branch.
 224 6. If there's any conflicts, they must be resolved.
 225 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
 226 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
 227    `gh` for verification against CI.
 228 9. If that fails, fixes continue and pushed up to `gh` as required.
 229 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
 230
 231 These steps are encapsulated in a script within `-portable`.  [Link](../maintscripts/sync-upstream.sh)
 232
 233 RELEASING A NEW VERSION
 234 =======================
 235
 236 Release for `-portable` try and align as close to upstream GoT as much as
 237 possible, even on the same day where that can happen.  That being said,
 238 sometimes a release of `-portable` might happen outside of that cadence, where
 239 a `-portable`-specific issue needs addressing, for example.
 240
 241 Before creating a new release, check the version of GoT as found in
 242 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
 243
 244 ```
 245 GOT_PORTABLE_VER=0.75
 246
 247 ```
 248
 249 Here, the *to be released* version of `got-portable` will be `0.75`.
 250 Typically, this version is incremented directly after a release, such that
 251 there's no need to change this value.  The only exception would be if there
 252 were an out-of-band release to `-portable`.  In such cases, that would take
 253 the form:
 254
 255 ```
 256 0.75.1
 257 ```
 258
 259 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
 260 from the `0.75` version.
 261
 262 The variable `GOT_RELEASE` needs be changed to `yes` so that the
 263 GOT_PORTABLE_VER is asserted correctly.
 264
 265 Once the version is verified, the following should be run from the `portable`
 266 branch -- and the repository should not have any outstanding modifications to
 267 the source:
 268
 269 ```
 270 make clean ; ./autogen && ./configure && make distcheck
 271 ```
 272
 273 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
 274
 275 This can then be copied to the `got-www` repository and uploaded, along with
 276 changing a couple of HTML pages therein to represent the new released version.
 277 Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
 278
 279 Once all of that has been done, the repository should be tagged to indicate
 280 the release, hence:
 281
 282 ```
 283 git tag -a 0.75
 284 ```
 285
 286 This can then be pushed out to `gh` and `origin`.
 287
 288 After that point, the version of `GOT_PORTABLE_VER` in
 289 `util/got-portable-ver.sh` should be changed to the next version, and
 290 `GOT_RELEASE` should be setg back to `no`.
 291
 292 TODO
 293 ====
 294
 295 * configure.ac should start defining AC_ENABLE arguments to allow for
 296   finer-grained control of where to search for includes/libraries, etc.
 297 * review the compat/ code.  Some of those functions are probably picked up in
 298   libbsd, so we should drop such implementations from compat/ where there's
 299   overlap between libbsd and what's natively available.
 300
 301 CONTACT
 302 =======
 303
 304 Thomas Adam <thomas@xteddy.org><br />
 305 thomas_adam (#gameoftrees on irc.libera.chat)
 306
 307 [1]  https://gameoftrees.org<br />
 308 [2]  https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
 309 [3]  https://github.com/ThomasAdam/got-portable