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