Contributing to XLM

We value community contributions of all kinds, including code, documentation, bug reports, feature ideas, and helping others in Discussions.

Ways to contribute

Pick the guide that matches your change:

Type	Guide
Add a maintained model (xlm-models/)	Adding a model
Add an external model (separate repo)	External models
Add a task or dataset (src/xlm/tasks/, dataset YAMLs)	Adding a task or dataset
Run your model on your task (external)	Running your model on your task
Core framework (src/xlm/)	Core development
Docs, bugs, issues	Docs and issues

Overview and links: Ways to contribute.

Getting started

The usual path is to open an issue (bug, feature, or design question) and then open a pull request that references it. Use the pull request template when opening a PR.

Good first issues

See Good first issue.

Reporting bugs and features

• Search existing Issues first.
• Unsure if it is a bug or your setup? Ask in Q&A Discussions.
• Use the issue templates: bug report, feature request, new model, new task.

Environment setup

Install from source

Prerequisites: Python 3.11+ (see setup.py) and conda.

1. Fork the repository and clone your fork:

   git clone git@github.com:<your-github-username>/xlm-core.git
   cd xlm-core
   git remote add upstream https://github.com/dhruvdcoder/xlm-core.git
   

2. Create a branch (do not commit directly on main):

   git checkout -b short-description-of-change
   

3. Create and activate a virtual environment:

   conda create -p .venv_xlm_core python=3.11.10 pip ipykernel -y
   conda activate ./.venv_xlm_core
   

4. Install xlm-core and xlm-models in editable mode (same optional extras as CI):

   pip install -e ".[all]"
   pip install -e ./xlm-models
   

5. Install development tooling (test, dev, docs, lint):

   pip install -r requirements/test_requirements.txt \
               -r requirements/dev_requirements.txt \
               -r requirements/docs_requirements.txt \
               -r requirements/lint_requirements.txt
   

6. Verify the installation:

   xlm --help
   pytest -m "not slow and not cli"
   

If you only need a subset of tooling (for example docs-only), see Dependencies for what each requirements file contains.

Running tests

Details: Running tests.

Fast loop (recommended while developing):

pytest -m "not slow and not cli"

Full suite (includes slow and CLI subprocess tests; some tests skip if resources are missing):

pytest

Coverage (configuration in pyproject.toml):

coverage run -m pytest -m "not slow and not cli"
coverage report

CI runs pytest -m "not gpu and not cli and not integration" on pull requests (see .github/workflows/tests.yml).

Style and static checks

There is no repo-wide Makefile; run tools from the activated environment.

• Format: black is configured in pyproject.toml (line length 79):

  black src xlm-models tests
  

• Lint / types: the lint requirements bundle includes flake8, mypy, and related plugins. Fix new warnings in code you change; avoid drive-by mass reformatting of unrelated files.

Documentation

• Sources live under docs/. Build locally with mkdocs build (see Docs and issues).
• Add new pages to the nav: in mkdocs.yml when they should appear in the sidebar.

Opening a pull request

1. Push your branch to your fork and open a PR against main on dhruvdcoder/xlm-core.
2. Fill out the pull request template: contribution type, summary, testing, docs.
3. Link related issues and note any new dependencies or optional extras.
4. Apply GitHub labels on the PR (not just the issue) so release notes categorize correctly: use the same label as the issue template when applicable (bug, enhancement, documentation, model, external-model, new-task). Add breaking-change when the PR changes APIs, configs, or behavior in a incompatible way.
5. Ensure tests and docs you touched still build.
6. Request review from maintainers when ready.

License

By contributing, you agree that your contributions will be licensed under the same terms as the project (MIT).