Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
74 lines (54 loc) · 2 KB

CONTRIBUTING.md

File metadata and controls

74 lines (54 loc) · 2 KB
Raw

Contributing

Thanks for your interest in improving xlua-decompiler.

Development setup

git clone https://github.com/GabHST/xlua-decompiler.git
cd xlua-decompiler
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Running the test suite

pytest                                            # unit tests only
pytest --cov=xlua_decompiler --cov-report=term    # with coverage

All new code must keep test coverage at or above 80 percent.

Linting and formatting

ruff check .
ruff format .

Both must succeed before opening a pull request. CI runs the same commands on every push.

Running the tool locally

Place a real xLua bytecode file under ./sample/ and a copy of unluac.jar at the project root, then:

python -m xlua_decompiler decompile sample/script.lua \
    --unluac unluac.jar \
    --overwrite \
    -o sample/script.dec.lua

Pull request checklist

  • New behaviour covered by tests
  • ruff check . passes
  • ruff format --check . passes
  • pytest passes locally
  • README or docstrings updated if user-facing behaviour changed
  • Commit messages follow the existing convention (feat:, fix:, refactor:, docs:, test:, chore:, perf:, ci:)

Reporting bugs

Open an issue with:

  1. The xLua bytecode format details if known (xLua version, Lua version).
  2. A minimal input file or the stack trace from the failure.
  3. The exact command line used and the unluac version you tested against.

Please do not attach proprietary or copyrighted content. Synthetic or public-domain samples only.

Scope

This tool intentionally focuses on a narrow problem: reshaping xLua's file header and root proto so that an unmodified unluac can decompile the rest. Feature requests that broaden the scope (e.g. re-implementing a Lua decompiler, shipping a patched unluac JAR, decrypting arbitrary obfuscated bundles) are unlikely to be merged.