chore/adrs-and-specs #188

Merged
OragonEfreet merged 37 commits from chore/adrs-and-specs into main 2026-11-03 14:31:38 +01:00
Owner

Create Architecture Decision Records (ADR)
Create Specs
Create tests for specs
Find any unsolved questions from specs and fix them all

Create Architecture Decision Records (ADR) Create Specs Create tests for specs Find any unsolved questions from specs and fix them all
OragonEfreet added this to the 1.1 milestone 2026-11-02 19:39:59 +01:00
- Add six MADR 4 records in docs/design/, ADR 0001 to ADR 0006.
- Add 49 behavioral specifications in docs/spec/, 18 complete and 31 still without example tables, with their rules in docs/spec/README.md.
- Move the tests of the complete specifications into test/spec_<domain>.c, a new Spec CTest category, so their CTest names change, such as [Unit] unit_math to [Spec] spec_math.
- Document ADRs, specifications and API naming in CONTRIBUTING.md.

The moved tests have not been built or run yet.
Squashes 4 commits:

- test(framework): parenthesize the operands of comparison checks
- test(framework): count cases and allocations without wrapping
- test(framework): report leaks when a case fails
- test(framework): flush case results before silencing a case
Squashes 6 commits:

- docs(build): list the version stages of version.h in CMakeLists.txt
- fix(build): stop linking libX11 and libasound
- build: deprecate BANJO_CONFIG_CHECKS_ABORT
- build(cocoa): stop linking QuartzCore
- refactor(cocoa): drop the (void) cast on the draw callback
- build: choose the precision of bj_real with BANJO_REAL_PRECISION
Squashes 6 commits:

- docs(vec): list what each vector size has
- test(vec): map the vector tests to vec-001
- test(vec): size the tiny vector from BJ_EPSILON
- fix(vec): normalize short vectors as scale_to_len does
- test(vec): specify normalizing short vectors
- docs(vec): say which way perp_dot turns on screen
Squashes 2 commits:

- test: check that spec cases match their TEST_CASEs
- test(link): check that optional platform libraries stay unlinked
Squashes 3 commits:

- ci(release): drop a nonexistent option and run the Linux tests
- ci(release): refuse a tag that does not match version.h
- docs(release): tag pre-releases published on the Releases page
Squashes 8 commits:

- fix(shader): centre pixel coordinates by half the bitmap's size
- docs(shader): describe the coordinates and colour a shader receives
- test(shader): specify shaders
- fix(shader): saturate colour components without the clamp flag
- test(shader): specify saturation without the clamp flag
- docs(shader): give half-open coordinate ranges and the real colour
- docs(shader): say what NULL does for bj_shade_bitmap()
- test(shader): specify shading a NULL bitmap or with no function
Squashes 2 commits:

- docs(main): say where main is renamed
- fix(main): return -1 when bj_call_main() has no function
Squashes 9 commits:

- docs(app): fix the allocation and pacing of the header examples
- docs(app): drop the suggestion of apps on several threads
- docs(app): say what NULL does for the application functions
- test(app): specify the frame rate settings and the loop pacing
- test(app): specify the fixed-step rate settings and the fresh-app defaults
- test(app): specify the drain order within an iteration and init_data
- test(app): pin the default fixed-step delta to exactly 1/60
- docs(app): drop the open question on the Emscripten path
- docs(app): drop the open question on the timing cases
Squashes 20 commits:

- fix(audio): open every device paused
- fix(audio): fail cleanly without audio or with a NULL device
- feat(audio): run the fake audio device on a playback thread
- docs(audio): describe the callback buffer, the sample index and NULL
- test(audio): specify audio devices
- fix(examples): name the audio properties of audio_pcm.c
- fix(audio): accumulate the phase of bj_play_audio_note
- docs(audio): describe the waveforms and formats of bj_play_audio_note
- test(audio): specify waveforms
- docs(audio): say that the fake device calls the callback
- fix(audio): make bj_play_audio_note write silence when it cannot play
- test(audio): specify the silence of bj_play_audio_note
- fix(audio): close the devices still open when audio ends
- test(audio): specify ending audio with a device open
- fix(audio): give every backend properties and a callback
- docs(audio): say what NULL does for the device and note functions
- test(audio): specify devices without properties or callback
- docs(audio): document the flag handoff with the audio thread
- docs(audio): drop the open question on native property mismatch
- docs(audio): document the shared note data
Squashes 46 commits:

- fix(bitmap): clamp each channel on its own in 32-bit saturating blits
- fix(bitmap): keep the scale when a stretched blit is clipped
- fix(bitmap): return NULL from bj_convert_bitmap for an invalid mode
- fix(bitmap): keep the clear colour and colour key in bj_copy_bitmap
- docs(bitmap): match the pixel access and blit comments to the code
- test(bitmap): map the bitmap and blit tests to bitmap-001 and bitmap-003
- fix(bitmap): alternate the nibbles of RLE4 runs
- docs(bitmap): match the BMP loading comment to the decoder
- test(bitmap): specify BMP loading
- fix(bitmap): read ANSI sequences in text the same way to draw and measure
- docs(bitmap): describe the characters and glyph size of text drawing
- test(bitmap): specify text drawing
- fix(bitmap): fill the whole destination in a stretched mask blit
- fix(bitmap): keep the scale when a stretched mask blit is clipped
- fix(bitmap): map stretched blits exactly
- fix(bitmap): clip a mask area that reaches past the mask
- fix(bitmap): keep the scale of text clipped at an edge
- docs(bitmap): describe mask blits
- test(bitmap): cover stretching by three and scaled text at the edges
- test(bitmap): specify mask blits
- test(bitmap): specify loading a BMP file with the 5-5-5 masks
- fix(bitmap): make bj_create_bitmap refuse modes it cannot hold
- test(bitmap): specify bitmaps without a stride or without pixels
- fix(bitmap): compare colour keys on the bits that hold colour
- test(bitmap): specify colour keys that differ in unused bits
- docs(bitmap): say that an indexed mode converts to and from black
- test(bitmap): specify conversions with an indexed mode
- docs(bitmap): document NULL for the copy and property functions
- test(bitmap): specify the properties of a NULL bitmap
- docs(bitmap): list the errors of bj_create_bitmap_from_file
- fix(bitmap): report running out of memory while converting a BMP
- test(bitmap): specify loading a BMP when memory runs out
- test(bitmap): specify creating bitmaps of rows too long for a size_t
- fix(bitmap): return NULL for a NULL path to load
- test(bitmap): specify loading a NULL path
- docs(bitmap): say what NULL does for every bitmap parameter
- test(bitmap): specify what NULL does to bitmaps, blits and text
- fix(bitmap): keep the mode of the empty bitmaps from pixels
- fix(bitmap): refuse the RLE files of negative height
- test(bitmap): pin what the questionable files become
- docs(bitmap): name the destination areas asymmetry as intended
- fix(bitmap): refuse the indexed modes in the colour blits
- test(bitmap): pin that a mask blit ran even without changing pixels
- fix(bitmap): centre the stretched blits' sampling
- docs(bitmap): state that text has no line breaks
- test(bitmap): pin the lone escape of the text drawing
Squashes 19 commits:

- fix(cli): match long options by their exact name
- fix(cli): report the documented error codes
- fix(cli): use argv[0] when the program name is not set
- fix(cli): reject overflowing doubles and negative unsigned values
- fix(cli): print the positional counts with matching formats
- docs(cli): describe help output, flags and the accepted values
- test(cli): specify argument parsing
- fix(cli): make an empty argument fill a positional in bj_parse_cli
- test(cli): specify empty arguments as positional values
- feat(cli): end the options at -- in bj_parse_cli
- test(cli): specify -- as the end of the options
- fix(examples): make banjo-info --help print the help and exit
- docs(cli): say that bj_print_cli_help_action can take a value
- fix(cli): stop crashing on NULL parsers, arguments and buffers
- test(cli): specify parsing and storing with NULL arguments
- docs(cli): say what NULL does for every parameter of cli.h
- test(cli): specify the help of a NULL parser
- fix(cli): find an overflowed double without isinf()
- docs(cli): drop the open question on the argumentless exit
Squashes 5 commits:

- docs(design): confirm that no backend links its library
- docs(design): accept one thread for process-wide state
- docs(design): confirm the backend order of ADR 0005
- test(design): check the format of the decision records
- docs(design): define the deprecation policy in ADR 0007
Squashes 6 commits:

- docs(compat): point the shim notes at CONTRIBUTING.md
- test(compat): map the compatibility tests to compat-001
- test(compat): exercise the deprecated mask blits
- test(compat): end Banjo before the report of spec_compat
- docs(compat): name the exception of the bitmap allocation functions
- test(compat): shape the compatibility specification around the shims
Squashes 13 commits:

- fix(event): poll without video
- docs(event): describe the queue, key filtering and Escape
- test(event): specify the event queue
- fix(event): ignore a NULL event when polling and dispatching
- test(event): specify NULL events
- docs(event): specify that setters do not return the old user data
- fix(event): queue nothing for bj_push_event(NULL)
- docs(event): say what NULL does for the event parameters
- test(event): specify pushing NULL and events of no window
- test(event): pin what a restart of event support keeps
- docs(event): say that pushing every round keeps the dispatch busy
- docs(event): state the window contract of key events
- docs(event): fence the real-input boundary
Squashes 13 commits:

- fix(draw): keep bj_draw_rectangle's outline inside its area
- fix(draw): draw the flat bottom edge of a filled triangle
- docs(draw): say that drawing clips to the bitmap
- test(draw): map the drawing tests to draw-001
- refactor(draw): fold the degenerate circle's callback result
- docs(draw): describe a NULL bitmap for the circle functions
- fix(draw): make bj_draw_filled_triangle cover its outline
- test(draw): specify that a filled triangle covers its outline
- docs(draw): say what NULL does for every drawing parameter
- test(draw): specify drawing into a NULL bitmap or area
- docs(draw): say that enumeration user data may be NULL
- fix(draw): keep the primitives defined at the int extremes
- test(draw): bound the extremes span of the extreme case
Squashes 6 commits:

- fix(geom): give a very short segment the same tolerance as others
- test(geom): specify touching within BJ_EPSILON
- docs(geom): say that touching counts, and with what tolerance
- test(geom): pin the degenerate segment, a point
- fix(geom): count a negative radius as a zero one
- fix(geom): make a point segment miss off the segment line
Squashes 12 commits:

- docs(log): state the threshold of bj_log_msg the right way round
- fix(log): log nothing for a NULL format
- test(log): specify logging without a format
- fix(log): name levels outside the enum UNKNOWN
- docs(log): say that bj_log_msg() takes a level name
- test(log): specify levels outside the enum
- refactor(log): delete the time and source code commented out
- fix(log): colour the level whenever its codes fit
- docs(log): describe the log line that is written
- test(log): specify the log line
- test(log): specify level names and a threshold above FATAL
- docs(log): state what the coloured build pins
Squashes 9 commits:

- fix(mat): return the inverse from bj_mat3_invert
- fix(mat): rotate 4x4 matrices by the right-hand rule
- docs(mat): match four doc comments to the code
- test(mat): map the matrix tests to mat-001
- fix(mat): keep the arcball cosine within [-1, 1]
- test(mat): specify arcball rotations between nearby points
- docs(mat): say what orthonormalizing a degenerate block gives
- test(mat): specify orthonormalizing a degenerate block
- fix(mat): let the transposes run in place
Squashes 7 commits:

- docs(math): state that matrix pointers are not checked
- docs(math): state that vec.h does not check function pointers
- docs(math): drop the duplicate-case note
- docs(math): drop the precision-CI note
- test(math): exercise the relative scale and comparators
- test(math): pin the negative mod divisor, name the caller errors
- test(math): call the typed wrapper names directly
Squashes 7 commits:

- test(maze): say why the backtracker shrinks once more than it grows
- test(maze): specify a reset that the setup refuses
- docs(maze): describe NULL arguments as the code handles them
- docs(maze): drop the history note from the open questions
- test(maze): pin the close of a slot with no cell to face
- test(maze): pin the allocation failure and the largest rejected count
- test(maze): dedupe the builder cards and complete the coverage
Squashes 9 commits:

- docs(memory): match the allocator comments to the code
- test(mem): map the allocator tests to mem-001
- fix(mem): refuse memory callbacks with a NULL function
- test(mem): specify that a set with a NULL function is refused
- docs(mem): ask to keep the memory callbacks for Banjo's lifetime
- fix(memory): stop passing NULL blocks to the C library
- test(memory): specify the memory functions of NULL
- docs(memory): say how the allocators treat NULL
- docs(mem): leave the zero sizes to the C library
Squashes 11 commits:

- test(net): check that an idle connection has nothing available
- test(net): make three cases check what they claim
- fix(net): return -1 for a NULL stream or buffer to transfer
- test(net): specify transfers with a NULL stream or buffer
- fix(net): fail on a NULL host to resolve, connect or send to
- test(net): specify resolving, connecting and sending to a NULL host
- docs(net): say what NULL does for every network parameter
- test(net): specify the address, TCP and UDP functions of NULL
- test(net): resolve the shapes that need no DNS
- test(net): pin the ephemeral port and the shutdown half
- test(net): pin the empty wait, and fence the UDP boundaries
Squashes 10 commits:

- fix(physics): add the weight in bj_apply_gravity_2d
- docs(physics): match the damping and point gravity comments to the code
- test(phys): map the physics tests to phys-001 to phys-004
- fix(physics): wrap the angle by as many turns as a step took
- test(physics): specify wrapping a step of several turns
- docs(physics): warn that bj_newton_gravitation divides by r squared
- fix(physics): do nothing for a NULL particle in gravity and drag
- docs(physics): say what NULL does for the 2D physics functions
- test(physics): specify the particle, angular and body functions of NULL
- fix(phys): say what damping does and let the infinite inertia keep its spin
Squashes 6 commits:

- test(pix): narrow the reversed line, and specify ties
- docs(pix): drop the questions about drawing out of bounds
- test(pix): specify the circle and grid walks without a callback
- test(pix): pin the circle walk details the header documents
- docs(pix): drop the stale open-question pointer in Rule 6
- test(pix): pin the grid ray values the header defines
Squashes 13 commits:

- docs(pixel): say which modes bj_compute_bitmap_stride handles
- test(pixel): map the pixel tests to pixel-001
- fix(pixel): give XRGB1555 for its own masks in bj_compute_pixel_mode
- test(pixel): specify the XRGB1555 masks in bj_compute_pixel_mode
- fix(pixel): give no colour to bitfield modes of an unknown layout
- test(pixel): specify bitfield modes of an unknown layout
- fix(pixel): widen 5- and 6-bit channels to the full 8-bit range
- test(pixel): specify widening and packing back
- fix(pixel): give no stride to a row too long for a size_t
- test(pixel): specify the stride of rows too long for a size_t
- fix(pixel): skip the channels left out of an unpacked pixel
- test(pixel): specify unpacking into some channels only
- test(pixel): pin what a bitfield order and an odd byte size do
Squashes 14 commits:

- fix(random): keep bj_random_uniform_ld below its upper bound
- test(rand): map the distribution tests to rand-002
- test(rand): compare the real selectors with the type of bj_real
- docs(random): document the shared PCG32 generator behind NULL
- test(rand): specify the shared PCG32 generator behind NULL
- fix(random): give the high bits to the first of two draws
- test(random): specify the order of the two draws
- fix(random): keep the real uniform draws below their upper bound
- test(random): specify draws that round up to high
- docs(random): say what reversed and degenerate arguments give
- fix(random): draw from bj_rand() when a distribution has no callback
- docs(random): say that bj_pcg32_generator() takes a NULL state
- test(random): specify drawing without a callback or a state
- test(rand): pin the PCG32 reference and a thousand stream pairs
Squashes 3 commits:

- docs(rect): describe NULL arguments as the code handles them
- test(rect): specify NULL arguments of the intersection and union
- test(rect): pin the negative positions and the flat rectangles
Squashes 4 commits:

- fix(stream): stop crashing on NULL streams and NULL data
- docs(stream): say what NULL does for the remaining parameters
- test(stream): specify NULL streams, data and buffers
- fix(stream): make the bare stream an empty valid one
Squashes 16 commits:

- fix(system): ignore the release of a subsystem that is not retained
- docs(system): describe what bj_begin starts
- test(sys): map the backend tests to sys-001
- fix(system): treat NULL library arguments alike on every platform
- fix(alsa): load libasound by its runtime name
- docs(system): describe NULL arguments and the lifetime of symbols
- test(sys): specify library loading
- fix(system): build without any video or audio backend
- test(sys): specify the priority order of the backend lists
- docs(system): name the backend priority order in the headers
- fix(system): retain time and events per system in bj_begin
- test(system): specify the retains of bj_begin
- fix(system): refuse combinations in bj_begin_system
- test(system): specify combinations and BJ_NO_SYSTEM
- docs(system): say that every error location may be NULL
- docs(sys): fence the backend-less and native-library boundaries
Squashes 12 commits:

- fix(time): keep sleeping when a signal interrupts bj_sleep_ms
- test(time): map the clock tests to time-002
- fix(time): stop the stopwatch reads writing to a const stopwatch
- test(time): specify reading a stopwatch never reset
- test(time): end Banjo before the report of spec_time
- fix(time): start the clocks on first use before bj_begin
- test(time): specify the clocks before bj_begin
- fix(time): return at once from a negative sleep on Windows
- test(time): specify negative sleeps
- docs(time): say what NULL does for the stopwatch functions
- test(time): specify the stopwatch functions of NULL
- fix(time): the first step of a fresh stopwatch returns 0
Squashes 11 commits:

- fix(version): count the stage number in bj_format_version's length
- test(version): specify the version macros and build info
- fix(version): report the CoreAudio and fake backends
- test(version): check the CoreAudio and fake build flags
- feat(version): report the size of bj_real
- test(version): check the size of bj_real
- docs(version): stop release candidate numbers at 62
- test(version): specify the last release candidate number
- fix(version): only measure for a NULL buffer of any size
- test(version): specify formatting into a NULL buffer of any size
- docs(version): say whose build the debug flag describes
Squashes 14 commits:

- fix(window): fail cleanly when video is not running
- fix(window): report a NULL window as closing
- docs(window): describe NULL windows and the order of a resize
- test(window): specify the window lifecycle
- test(window): specify resizing and fullscreen
- test(window): drop the stale reference to unit_draw_callback.c
- docs(window): say where the keyboard state comes from
- test(window): specify keyboard state
- fix(window): destroy the windows still open when video ends
- test(window): specify ending video with a window open
- fix(window): give every backend a title, empty for NULL
- docs(window): say what NULL does for the remaining parameters
- test(window): specify creating a window with no title
- test(window): pin the quiet birth and the display-sized fullscreen
Squashes 9 commits:

- docs(error): stop calling a NULL error location zero-cost
- docs(error): narrow the error-location convention
- docs(error): say what NULL does for every error parameter
- docs(error): state where the discarded error is logged
- test(error): pin the exact prefixed message
- test(error): pin the propagate into a taken location
- test(error): prefix through a NULL location
- test(error): pin the out of memory behavior
- docs(error): drop the question the allocation pins answered
Squashes 6 commits:

- test(spec): accept specifications checked by review
- docs(spec): check assert-001, main-001 and api-001 by review
- docs(spec): record that deprecated names do not warn
- docs(spec): say that unit_string.c covers string.h
- docs(spec): leave the deprecation status out of the specifications
- docs(spec): drop the settled Open questions sections
fix(docs): unglue the colon after the bj_end reference
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 8s
Documentation / build-docs (pull_request) Successful in 15s
QA / cert (pull_request) Successful in 30s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 21s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 22s
Build and Test / linux-windows-mingw / shared (pull_request) Successful in 29s
Build and Test / linux-windows-mingw / static (pull_request) Successful in 30s
C++ Compatibility / C++ Compatibility Check (push) Successful in 7s
Documentation / build-docs (push) Successful in 10s
QA / cert (push) Successful in 30s
Build and Test / linux-linux-gcc / shared (push) Successful in 21s
Build and Test / linux-linux-gcc / static (push) Successful in 23s
Build and Test / linux-windows-mingw / shared (push) Successful in 29s
Build and Test / linux-windows-mingw / static (push) Successful in 29s
d35c117404
Squashes 13 commits:

- docs(core): say that the build mode follows the including code
- docs(building): document the presets CMakePresets.json defines
- docs(building): fix the backend sources, flags and manual build
- docs(readme): complete the contents, CI and dependencies
- docs(contributing): name the BANJO_ macros and the Objective-C file
- docs(integrating): pin v1.0.0 and complete the manual link lines
- docs(changelog): note the source break of the loss simulation
- docs(api): list maze.c and pixel_enumeration.c among the examples
- docs(contributing): state the rule for NULL arguments
- docs(contributing): leave room for documented meanings of NULL
- docs(contributing): categorize the tests by their question
- docs(workflow): add the when-to-write-what memo and the directory guides
- fix(docs): unglue the colon after the bj_end reference
OragonEfreet deleted branch chore/adrs-and-specs 2026-11-03 14:31:38 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
OragonEfreet/banjo!188
No description provided.