Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
254 lines (175 loc) · 7.18 KB

CONTRIBUTING.md

File metadata and controls

254 lines (175 loc) · 7.18 KB

Contributing to Bobbin

Thanks for wanting to contribute!

Prerequisites

Development Setup

After cloning the repo, run the setup script to link the Bobbin addon into the Godot test project:

Windows (PowerShell):

.\scripts\setup.ps1

Linux/Mac:

chmod +x scripts/setup.sh
./scripts/setup.sh

This creates a junction (Windows) or symlink (Linux/Mac) so that changes to godot/addons/bobbin/ are immediately reflected in the test project, and builds the Docker image for containerized builds. You only need to run this once per clone.

Building with Docker

From the repo root:

# Local development (fast builds)
docker compose run --rm --build godot windows
docker compose run --rm --build godot windows debug
docker compose run --rm --build godot all              # all platforms × all types

# All platforms, single build type
docker compose run --rm --build godot all release
docker compose run --rm --build godot all debug

# CI builds (optimized, smaller binaries)
docker compose run --rm --build godot all --ci

Artifacts are automatically copied to bindings/godot/addons/bobbin/bin/.

Build Options

Target Debug Release Notes
windows .debug.dll .dll Cross-compiled via mingw-w64
linux .debug.so .so Native Linux build
wasm .wasm .wasm Debug only; fixed name required by gdext
all All targets All targets Builds all platforms × all types by default
Flag Effect
--ci Use optimized profiles (slower build, smaller binaries)

Notes:

  • By default, builds use fast profiles for quick local iteration. Use --ci for optimized release builds.
  • macOS builds are not supported by the Docker container (cross-compiling for macOS requires Apple SDK). macOS builds will be handled by CI/CD on native macOS runners.
  • WASM release builds are not yet supported due to nightly toolchain requirements.

Testing

Godot Integration Tests

Open test-projects/godot/bobbin-test-project/ in Godot Editor.

Runtime Unit Tests

cargo test -p bobbin-runtime

Runtime Development

Test Organization

Runtime tests live in runtime/tests/ with this structure:

  • basic.rs — Simple dialogue tests
  • choices.rs — Choice/branching tests
  • commands.rs — Command invocation tests
  • conditionals.rs — Conditional (if/elseif/else) tests
  • expressions.rs — Expression operator tests
  • variables.rs — Variable and interpolation tests
  • syntax.rs — Syntax error tests
  • support/ — Test utilities and runners
  • cases/ — Test case data files organized by feature

Run a specific test category:

cargo test -p bobbin-runtime --test choices

Adding a New Test

  1. Create a .bobbin file in the appropriate cases/ subdirectory
  2. Create a sidecar file with expected output:
    • .out for linear output tests (one expected line per line)
    • .trace for interactive tests with choices (see format below)
    • .err for error tests (substrings that must appear in error message)
  3. Add a #[test] function in the corresponding test file (e.g., choices.rs)

Sidecar File Formats

.out — Expected output lines (one per line):

Hello, World!
How are you?

.trace — Execution trace with named paths for interactive tests:

--- path: select_first
> How are you?
[advance]
? Good | Bad
[choice 0]
! done

--- path: select_second
> How are you?
[advance]
[choice 1]
! done

Format elements:

  • --- path: <name> — Start named execution path
  • > <text> — Assert current_line() equals text
  • ? A | B — Assert current_choices() equals ["A", "B"]
  • ! done — Assert has_more() is false
  • ! has_more — Assert has_more() is true
  • ! waiting_for_choice — Assert is_waiting_for_choice() is true
  • ! command <name>(<args>) — Assert command was called with given arguments
  • [advance] — Call advance()
  • [choice <n>] — Call select_choice(n)
  • [host <var> = <value>] — Set extern variable before execution
  • [command <name>(<arity>) = mock] — Register mock command with given arity
  • # comment — Comment (ignored)

.err — Substrings that must appear in error message (one per line, case-insensitive):

undefined
name

Editor Tooling Development

Bobbin includes an LSP server and VS Code extension for editor support.

LSP Server

The language server lives in lsp/ and provides diagnostics to any LSP-compatible editor.

# Build and install
cargo install --path lsp

# Or just build for development
cd lsp && cargo build

VS Code Extension

The extension lives in editors/vscode/.

Setup:

cd editors/vscode
npm install
npm run compile

Running (choose one):

  1. Extension Development Host — Press F5 with the extension folder open, or select "Run Bobbin Extension" from the debug dropdown at the repo root.

  2. Install in your VS Code — Link the extension into your extensions folder:

    Windows (CMD):

    mklink /J "%USERPROFILE%\.vscode\extensions\bobbin-vscode" "C:\path\to\bobbin\editors\vscode"

    macOS/Linux:

    ln -s /path/to/bobbin/editors/vscode ~/.vscode/extensions/bobbin-vscode

    Then reload VS Code (Ctrl+Shift+P → "Reload Window").

After changes:

  • TypeScript changes: npm run compile then reload VS Code
  • LSP changes: cargo install --path lsp then reload VS Code

Releasing

Godot Addon

Releases are automated via GitHub Actions. There are two ways to trigger a release:

Option 1: Tag push (recommended)

# Update version in bindings/godot/Cargo.toml, then:
git tag godot-addon-v1.0.0
git push origin godot-addon-v1.0.0

Option 2: Manual dispatch

  1. Go to Actions → "Release Godot Addon"
  2. Click "Run workflow"
  3. Enter the version (e.g., 1.0.0)
  4. Click "Run workflow"

The workflow builds for Windows, Linux, macOS, and WASM, then creates a GitHub Release with the addon zip attached.

Version Conventions

  • Use semantic versioning: MAJOR.MINOR.PATCH
  • Tag format: {component}-v{version} (e.g., godot-addon-v1.0.0)
  • Each distributable is versioned independently

Before you submit

By submitting a pull request, you agree that:

  • You have the right to submit the code (it's yours, or you have permission)
  • Your contribution will be incorporated into the project and distributed under the Bobbin License
  • You retain copyright to your contribution
  • You grant Snowfrog Studio a non-exclusive, perpetual, worldwide license to use, modify, relicense, or sublicense your contribution as part of the Bobbin project — including for commercial purposes

This keeps the project consistently licensed and allows for future possibilities such as commercial arrangements with studios.

See LICENSE.md for the full project license terms.