Contributing to neuralset

Thanks for your interest in contributing! Before diving in, see the design philosophy for the principles behind neuralset’s API (pydantic everywhere, lazy evaluation, the event abstraction).

Ways to Contribute

  • Bug reports — open an issue with a minimal reproducer.

  • Bug fixes — include a regression test.

  • New datasets or features — please open an issue first to discuss.

  • Documentation — typo fixes, examples, tutorials are always welcome.

Fork & Pull-Request Workflow

  1. Fork the repository on GitHub and clone your fork locally.

  2. Create a branch from main (or the current dev branch):

    git checkout -b my-feature

  3. Make your changes — follow the code style below.

  4. Run the checks before committing:

    cd neuralset-repo
ruff check neuralset/
mypy neuralset/
pytest neuralset/ -x -q

  5. Commit — pre-commit hooks will auto-format with black/isort and lint with ruff. If a hook fails, fix the issue and commit again.

  6. Push your branch and open a Pull Request against the upstream repo.

  7. A reviewer will check code quality, test coverage, and API consistency.

Tip

Keep PRs focused — one logical change per PR. PRs are squash-merged; intermediate commit messages don’t matter.

Reporting & Fixing Bugs

  • Search first — check existing GitHub issues to avoid duplicates.

  • File a bug with: a clear title, minimal reproduction steps, expected vs. actual behaviour, and your environment (Python version, OS, package version).

  • Fix a bug — if you want to fix it yourself:

    1. Write a failing test that reproduces the bug.

    2. Implement the fix.

    3. Verify the test now passes.

    4. Open a PR referencing the issue.

Code Quality & Pre-Commit Hooks

Pre-commit hooks run automatically on git commit:

Hook

What it does

black

Auto-formats Python code (line length, quotes, etc.)

isort

Sorts and groups import statements

ruff

Fast linter — catches style issues, unused imports, etc.

You can also run them manually:

cd neuralset-repo
ruff check neuralset/           # lint
mypy neuralset/                 # type check
pytest neuralset/ -x -q         # tests

To run hooks on all files (useful before a PR):

pre-commit run --all-files

All public APIs must have type annotations. Use tp.ClassVar for class constants, tp.Literal for string enums, pydantic BaseModel fields for configuration.

Use of Generative AI

Contributors are welcome to use AI tools (Copilot, ChatGPT, etc.) as aids, subject to these rules:

  • You are responsible for all code you submit. Review and understand every line before opening a PR.

  • Do not submit AI output you don’t understand. If you can’t explain a change, don’t submit it.

  • No AI bots interacting with the project. Automated agents must not open issues, submit PRs, post comments, or review code on behalf of contributors.