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