6 Contributor’s Guide
6.1 Setting up for development
On Windows without make, I recommend choco install make.
- Install Racket. For example, on macOS with homebrew you might run
brew install --cask racket
Clone the benknoble/frosthaven-manager repository.
- 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.
6.4 Debugging
The main application has a Debug menu that can run various tools, such as getting a flickering canvas when GC occurs to diagnose memory issues.
There is also a "gui/deserialized-state.rkt" module that can be run with
racket -l frosthaven-manager/gui/deserialized-state <save-file>
to debug the state saved with the Save Game menu item; this is one useful way to capture internal state and inspect it.
The main application accepts a –debug flag to start GUI Easy’s debugger and Racket debugger, too. The latter can be connected to with raco dbg if you have the dbg-ui package.