6 Contributor’s Guide🔗

6.1 Setting up for development🔗

On Windows without make, I recommend choco install make.

1. Install Racket. For example, on macOS with homebrew you might run

   brew install --cask racket

2. Clone the benknoble/frosthaven-manager repository.

3. Install the package as a link. For example, you might go to the cloned directory and run

   make install

6.1.1 Running tests🔗

You can run automated tests with

make test

You may prefer to pass RACO_TEST_ARGS=-x to skip modules without tests.

Manual GUI tests can be run by running the program or application, e.g., with racket gui/manager.rkt for the Frosthaven Manager. Many GUI modules come with manual demos of the components they provide.

You can also build executables and distributions using the corresponding make targets.

6.1.2 Rebuild the package🔗

This makes sure that your local installation is compiled, that the docs are up-to-date, and that the dependencies are appropriately adjusted.

make fix-deps

You should manually verify any dependency updates. The command git diff info.rkt will show any changes to the dependencies.

6.1.3 View the local documentation🔗

Run the following command:

raco docs frosthaven-manager

Or, to look for documentation for a specific thing, like creature, run

raco docs creature

You’ll want to make sure you select the search entry related to the Frosthaven Manager.

6.2 Contributing guidelines🔗

All contributors are expected to behave like polite, respectful adults. Anything less will not be tolerated. This project is committed to maintaining respect and equality for all people.

Many forms of contributing are accepted, including helping with social processes, maintaining text such as documentation, and writing code. If you don’t want to contribute code, you can still contribute to Frosthaven Manager.

Contributions to code should come with best effort documentation. If you aren’t used to Scribble yet, write some Markdown or plain text and let us help you convert it to Scribble. If you aren’t sure what to write, make an attempt and let us help you improve it.

Contributions to code may also come with tests. This is preferred but not required. It should be possible to somehow demonstrate that the contribution works correctly.

Style-wise: prefer the local customizations documented in Navigating the code. Prefer functional, immutable idioms where possible.

6.3 Navigating the code🔗

A full reference is provided at Developer Reference.

Frosthaven Manager makes extensive use of Qi: An Embeddable Flow-Oriented Language. Local customizations can be found in frosthaven-manager/qi/list2hash, frosthaven-manager/qi/utils, and frosthaven-manager/curlique.

Frosthaven Manager uses gui-easy: Declarative GUIs to build declarative GUIs. Local customizations to the observable operators can be found in frosthaven-manager/observable-operator.

Most of the game-related definitions are in frosthaven-manager/defns. Support for elements and their images is in frosthaven-manager/elements. Most GUI components are in modules under frosthaven-manager/gui. The Frosthaven Manager application is frosthaven-manager/gui/manager with state provided by frosthaven-manager/manager. The monster database is manipulated by frosthaven-manager/monster-db.

The module frosthaven-manager/enum-helpers provides a utility for modifying enum types from Enum Types.