Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
251 lines (165 loc) · 3.54 KB

CONTRIBUTING.md

File metadata and controls

251 lines (165 loc) · 3.54 KB
Raw

Contributing to Lux

Thank you for your interest in contributing to Lux!

Lux is an open-source puzzle platform featuring:

  • A Flask-based puzzle server
  • A CLI agent for solving puzzles
  • Ollama-powered contextual hints
  • Docker-based validation for code challenges
  • Automated testing, linting, and security scanning

We welcome bug fixes, new puzzles, documentation improvements, tests, and new features.

Development Setup

Prerequisites

  • Python 3.10+
  • Git
  • Docker (for script-based puzzle validation)
  • Ollama (optional, required for AI hints)

Clone the Repository

git clone https://github.com/johnny603/lux.git
cd lux

Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate

Install Dependencies

Application dependencies:

pip install -r requirements.txt

Development dependencies:

pip install -r requirements-dev.txt

Running the Project

Start the Puzzle Server

python3 server.py

By default the server listens on:

http://127.0.0.1:5050

Start the Agent

In a separate terminal:

source venv/bin/activate
python3 agent.py

If using a custom server URL:

export PUZZLE_SERVER=http://127.0.0.1:5050
python3 agent.py

Ollama Setup (Optional)

Install Ollama and ensure a model is available locally:

ollama pull llama3.2
ollama serve

The agent uses Ollama to generate hints while avoiding direct solutions.

Testing

Run all tests:

pytest

Current tests are located in:

tests/

When adding new functionality, please add tests when practical.

Linting

Run Ruff:

ruff check .

Check formatting:

ruff format --check .

Auto-format:

ruff format .

Security Checks

Run Bandit:

bandit -r .

Security checks are also performed automatically through:

  • Bandit
  • CodeQL
  • Snyk
  • Dependabot

Pull Request Process

  1. Fork the repository.
  2. Create a feature branch.
  3. Make your changes.
  4. Run:
ruff check .
pytest
bandit -r .
  1. Commit using Conventional Commits.
  2. Open a Pull Request.

Conventional Commits

Please follow the Conventional Commits specification.

Examples:

feat: add new puzzle category
fix: correct level validation logic
docs: update installation guide
test: add API smoke tests
refactor: simplify puzzle lookup
chore: update dependencies
ci: add CodeQL workflow

For breaking changes:

feat!: redesign puzzle API

or

feat(api): redesign puzzle API

BREAKING CHANGE: endpoint responses changed

Areas for Contribution

Some ideas for contributors:

  • Add new Linux puzzles
  • Add new C programming puzzles
  • Improve Docker sandboxing
  • Add web UI support
  • Add progress persistence
  • Improve Ollama prompt engineering
  • Expand automated test coverage
  • Improve documentation

Code Style

  • Prefer clear, readable code.
  • Keep functions focused and small.
  • Add comments when behavior is non-obvious.
  • Avoid unnecessary dependencies.
  • Maintain compatibility with Python 3.10+.

Reporting Issues

Before opening an issue:

  • Search existing issues first.
  • Include reproduction steps.
  • Include relevant logs and screenshots.
  • Provide environment information.

Use the provided issue templates whenever possible.

Code of Conduct

Be respectful and constructive.

We welcome contributors of all experience levels and encourage collaboration, learning, and knowledge sharing.

Thank you for helping improve Lux!