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