{"size": 3700, "ext": "scrbl", "max_stars_repo_path": "scribblings/maintainers.scrbl", "max_stars_repo_name": "dalev/racket-vulkan", "max_stars_repo_stars_event_min_datetime": "2019-10-18T18:39:55.000Z", "max_stars_repo_stars_event_max_datetime": "2021-11-16T21:50:30.000Z", "max_issues_repo_path": "scribblings/maintainers.scrbl", "max_issues_repo_name": "dalev/racket-vulkan", "max_issues_repo_issues_event_min_datetime": "2019-10-09T21:30:23.000Z", "max_issues_repo_issues_event_max_datetime": "2022-03-02T02:22:15.000Z", "max_forks_repo_path": "scribblings/maintainers.scrbl", "max_forks_repo_name": "dalev/racket-vulkan", "max_forks_repo_forks_event_min_datetime": "2019-10-22T23:42:40.000Z", "max_forks_repo_forks_event_max_datetime": "2022-02-15T23:32:21.000Z"}
{"max_stars_count": 45, "max_issues_count": 18, "max_forks_count": 8, "avg_line_length": 40.2173913043, "max_line_length": 99, "alphanum_fraction": 0.7945945946}
#lang scribble/manual

@title{Contributing}

The official repository @hyperlink["https://github.com/zyrolasting/racket-vulkan"]{is on GitHub}.
The source code tracks the @hyperlink["https://www.khronos.org/registry/vulkan/"]{Vulkan Registry}.

@section{What's Needed Right Now}
This collection depends on contributions of code or funding to keep up
with the rapid development of Vulkan. The GitHub README shows funding
oppurtunities, while this document focuses on technical contributions.

@bold{Right now the project has a strong need for example Vulkan
applications.} You can make an impact by porting C programs to Racket.
Each such application acts as a functional test for continuous
integration purposes, which covers far more than unit tests
ever could.

@section{Maintenance Guide}
This section is only meant to aid high-level understanding
of the project and its technical needs. It is not a reference
for implementation details.

@subsection{System Design}
This project's job is to generate Racket code that uses Vulkan
according to an end user's assumptions.

The system must remain flexible in the face of any change to a
machine-readable Vulkan specification. It does this by giving an
@italic{end user} the means to keep their Racket code up to date with
Vulkan, even if the source code of this project is @italic{out of
date}.

This is possible because the specification and code generators can
change independently, and are accessible through a public API.

@tt{vk.xml} in particular acts as input to all code generators in the
project. Each generator lazily produces a sequence of code from a
specification according to its own assumptions. You have to know how
to apply generators together to do something meaningful. I did it this
way because even backwards-compatible changes to a Vulkan
specification can break a model of it, so having a collection of
specialized generators makes it easier to manage assumptions.

@subsection{Maintenance Tasks}
This project maintains its own mirror of @tt{vk.xml} so it can
function offline, and the built-in code generators track its
contents. To update the project, maintainers should periodically write
a new version of the XML mirror, regenerate a Vulkan integration, and
run all relevant tests.

Here is a session I normally use to update the project, assuming the
package is installed on the system using @litchar{raco pkg install
--link}. I use fake paths to relevant files in the below snippet in
case the actual files move around the project.

@verbatim[#:indent 4]|{
# Download the latest vk.xml and replace the local mirror
ravk --latest show spec > /path/to/vk.xml

# Regenerate the unsafe FFI bindings.
# If this errors out, a code generator hit a runtime error
# and is likely incompatible with the XML update.
ravk generate unsafe > /path/to/unsafe.rkt

# Recompile the project.
# If this errors out, the unsafe bindings contain
# incorrect Racket code. This points to a logic
# error in a code generator.
raco setup vulkan

# Run unit tests
raco test --jobs 8 --drdr -p vulkan

# If Vulkan is actually installed on the system,
# use Racket or GRacket to use example
# applications as functional tests.
racket /path/to/examples/app1.rkt
racket /path/to/examples/app2.rkt
...
}|

Going through this script creates confidence in the package
and a Vulkan specification upgrade.

Should a new @tt{vk.xml} undergo a backwards-incompatible change, the
code generators should be archived such that they apply to prior
versions. A new set of code generators should henceforth process
the local mirror. There is not yet a way to pick only relevant
code generators given a spec version, but the implementation
will come when it's needed.
