Fix Bug Workflow

Systematic approach to fixing bugs with proper testing and documentation.

Workflow

1. Reproduce the Bug

Run the provided command or test to observe the failure:

# For WAST tests
./wasmoon test <file>.wast

# For MoonBit tests
moon test -p <package> -f <file>.mbt

# For specific test by index
moon test -p <package> -f <file>.mbt -i <index>

Document:

• Error messages
• Stack traces
• Expected vs actual behavior
• Steps to reproduce

2. Analyze Root Cause

Investigate the error systematically:

a) Examine error messages

• Identify the failing component
• Note line numbers and function names

b) Locate relevant code

• Use Glob to find implementation files: **/*<keyword>*.mbt
• Use Grep to search for specific functions or patterns
• Read source code in relevant modules

c) For WASM-related bugs

./wasmoon explore <file>.wat --stage ir vcode mc

Check IR, VCode, and machine code for issues.

d) For crashes or segfaults

lldb -- ./wasmoon test <file>.wast
(lldb) run
(lldb) bt  # After crash

3. Create Regression Test

Before fixing, write a test that reproduces the bug:

For WASM execution bugs:

test "descriptive_bug_name" {
  let source =
    #|(module
    #|  (func (export "test") (result i32)
    #|    ; Bug-reproducing code here
    #|  )
    #|)
  let result = compare_jit_interp(source, "test", [])
  inspect(result, content="matched")
}

For unit tests:

test "descriptive_bug_name" {
  let result = buggy_function(input)
  inspect(result, content="expected_value")
}

Place the test in the appropriate *_test.mbt file in the relevant package.

Verify the test fails:

moon test -p <package> -f <test_file>.mbt

4. Implement Fix

Make the necessary code changes:

• Fix the root cause, not just symptoms
• Follow coding standards (see ERRATA.md and CLAUDE.md)
• Keep changes minimal and focused
• Avoid refactoring unless necessary

Run tests to verify:

moon test -p <package>      # Unit tests
moon test                    # All tests
moon build && ./install.sh  # For wasmoon binary changes

5. Verify No Regressions

Ensure the fix doesn't break other functionality:

moon test                    # All unit tests
python3 scripts/run_all_wast.py --rec  # All wast tests

6. Create Pull Request

a) Create feature branch

git checkout -b fix/<descriptive-name>

b) Commit changes

moon fmt && moon info
git add .
git commit -m "$(cat <<'EOF'
fix: <brief description>

- Root cause: <explanation>
- Solution: <what was changed>
- Test: <test that verifies the fix>

EOF
)"

c) Push and create PR

git push -u origin fix/<descriptive-name>
gh pr create --title "fix: <brief description>" --body "$(cat <<'EOF'
## Summary
- Root cause: <explanation>
- Solution: <what was changed>
- Test: <test file and description>

## Test Plan
- [ ] Regression test passes
- [ ] All existing tests pass
- [ ] Manual verification of fix

EOF
)"

Best Practices

• Always create a regression test before fixing
• Keep fixes minimal and focused
• Test both the fix and potential regressions
• Document the root cause in commit messages
• Follow project commit message conventions
• Never use commit --amend or push --force on shared branches

Command Reference

# Build and install
moon build && ./install.sh

# Run tests
moon test -p <package> -f <file>.mbt
moon test -p <package> -f <file>.mbt -i <index>

# Analyze WASM
./wasmoon explore <file>.wat --stage ir vcode mc
./wasmoon test <file>.wast
./wasmoon test --no-jit <file>.wast

# Debug with LLDB
lldb -- ./wasmoon test <file>.wast

# Git workflow
git checkout -b fix/<name>
git add . && git commit
git push -u origin fix/<name>
gh pr create