Contributingο
Thanks for your interest in the project β youβre awesome! ππ
Any kind of help is welcome (Code, Bug reports, Content, Data, Documentation, Design, Examples, Ideas, Feedback, etc.). Issues and Pull Requests are encouraged: from a tiny typo fix to a new feature. Help us make SDialog better π
You can use the Edit button (pencil icon) on GitHub to quickly propose changes to any file via the web UI.
We follow Chris Beamsβ guidelines for commit messages.
Development installationο
git clone git@github.com:idiap/sdialog.git
cd sdialog
pip install -e .
Note
If you plan to work with audio capabilities, first install the required system dependencies, then install SDialog locally with:
pip install -e .[audio]
For Mac users (zsh shell), youβll need to quote the argument:
pip install -e '.[audio]'
Running tests & styleο
flake8 --ignore=W503 --max-line-length=120
pytest -v
Coverage (HTML + terminal):
pytest -v --cov=src/sdialog --cov-report=term-missing --cov-report=html
# Open htmlcov/index.html
Manual documentation buildο
Generate HTML:
cd docs
python -m sphinx -T -b html -d _build/doctrees -D language=en . ../docs_html
Regenerate API reference (only needed if new submodules are are added):
cd docs
sphinx-apidoc -f --ext-autodoc -o api ../src/sdialog
ReadTheDocs latest build list: https://app.readthedocs.org/projects/sdialog/
Release (PyPI)ο
Update version in
src/sdialog/util.py(follow semver)Update CHANGELOG (if present)
Tag & push
git commit -m "Release v0.x.x"
git tag v0.x.x
git push origin main --tags
Build & upload:
python -m build
python -m twine upload dist/*
Guidelinesο
Keep functions/classes small & composable
Add/extend tests for new features or bug fixes
Document public APIs (docstrings + docs reference where appropriate)
Prefer pure functions where state is not needed
Avoid introducing heavy deps without discussion (open issue first)
Use meaningful names; avoid abbreviations except standard ones (LLM, NLP, etc.)
Adding tutorials / notebooksο
Place new notebooks in the tutorials/ folder matching their goal (dialog_generation/, audio/, agents/ or interpretability/), keep naming numeric + descriptive (e.g., 3.new_feature_example.ipynb), and add them to the index in tutorials/README.md. Ensure they run top-to-bottom in Colab. Use lightweight models or small number of elements to keep runtime short.
Opening an issueο
Provide:
Summary
Steps to reproduce (if bug)
Expected vs actual
Environment (Python version, OS, backend model)
Minimal reproducible code snippet
Pull request checklistο
[ ] Feature / bug issue linked (if applicable)
[ ] Tests added or updated
[ ] Docs / examples updated
[ ] No lint errors
[ ] Local tests pass
[ ] Changelog updated (if user-facing change)
Communicationο
Use GitHub Issues / Discussions for feature proposals. For larger changes, open a draft PR early for feedback.
AI-assisted developmentο
This project provides an llm.txt file following the llms.txt specification for AI coding assistants. GitHub Copilot and other AI tools can fetch structured project information with: #fetch https://sdialog.readthedocs.io/en/latest/llm.txt
Thanksο
Your contributions make the project better for everyone. π