1How to hack on Chafa
2====================
3
4Code formatting and structure
5-----------------------------
6
7The code is mostly C99 with limited use of extensions. It should compile with
8most standards-compliant C compilers released in the last couple of years.
9
10GLib is our primary support library, and the code is in general very GLib-y.
11We use only the base library, no GObject or GIO.
12
13Formatting is done with spaces (no tabs) and four-space indenting stops.
14
15The directory layout is as follows:
16
17* Top level ............ Build scripts, README, etc.
18  |- chafa ............. The Chafa library. All exported APIs are here.
19  |  `- internal ....... Chafa library internals. Internal APIs.
20  |     `- smolscale ... Private copy of a pixmap scaling library.
21  |- docs .............. Built documentation (API and man pages).
22  |- libnsgif .......... Private copy of a GIF library, used by tools.
23  `- tools ............. Command-line tools.
24     |- chafa .......... The Chafa command-line graphics viewer.
25     `- fontgen ........ Experimental font generator.
26
27Making source releases
28----------------------
29
30Releases are made as compressed, signed tar archives ("tarballs"). We use
31semantic versioning.
32
33The following can be done multiple times and at any time during development,
34always on the master branch:
35
361) Write/edit NEWS section with a (TBA) placeholder for release date.
37
38Then right before the release, still on the master branch:
39
402) Update the soversion in chafa/Makefile.am (-version-info c:r:a):
41   - If the library source code has changed at all since the last update,
42     then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
43   - If any interfaces have been added, removed, or changed since the last
44     update, increment current, and set revision to 0.
45   - If any interfaces have been added since the last public release, then
46     increment age.
47   - If any interfaces have been removed or changed since the last public
48     release, then set age to 0.
49
503) If this is a minor (x.y.0) release, bump package to the next even version
51   in configure.ac.
52
534) Make sure 'make distcheck' passes. Correct any issues.
54
555) Commit and push above changes. Wait for green CI and correct any issues.
56
576) Edit NEWS and replace (TBA) with today's date.
58
597) If this is a minor (x.y.0) release, edit README.md and update the CI links.
60   They should reference master and the latest stable branch.
61
628) If this is a micro (x.y.z) release, switch to that release's maintenance
63   branch (x.y) and cherry-pick all changes from the previous steps into it,
64   then increment the micro version in configure.ac.
65
669) Commit above changes.
67
6810) Tag and sign the release: 'git tag -s x.y.z'. Annotate with the appropriate
69    NEWS item, without the --- underline for the heading.
70
7111) If this is a minor (x.y.0) release, make a maintenance branch for it,
72    rooted at the tag: 'git branch x.y'. But keep working on master.
73
7412) Build tarball: 'make distcheck'.
75
7613) Sign tarball: 'gpg --sign --detach --armor chafa-x.y.z.tar.xz'.
77
7814) If this was a minor (x.y.0) release, bump package to the next odd version.
79
8015) Commit the post-release version bump.
81
8216) Push changes. Make sure to push tags and branches too.
83
8417) Upload the tarball and signature to GitHub, and copy the NEWS item there.
85    Add markdown formatting.
86
87That should do it.
88