Contribute to TJBot

TJBot: Community Edition is an open source project and contributions are welcome! This page covers the basic workflow for setting up a local development environment for hacking on TJBot's software libraries.

TypeScript development

TJBot's TypeScript workflow is centered around a local checkout of the node-tjbotlib library and linking it to your recipes.

1. Clone node-tjbotlib

TJBot's Node.js library is called node-tjbotlib and is implemented in Typescript. Create a fork of the node-tjbotlib repository and check it out locally. We recommend placing it under ~/.tjbot so it is easy to find and reuse across recipes.

mkdir -p ~/.tjbot
cd ~/.tjbot
git clone <your-fork-url-of-node-tjbotlib>
cd node-tjbotlib

2. Register the library with npm

Run npm link inside node-tjbotlib so npm knows about your local copy of the package.

npm link

This creates a global symlink for the package and makes it available to local recipes without publishing a new version.

3. Link a recipe to the local library

In directory of the recipe you want to work on, link the local tjbot package name to your checkout of node-tjbotlib.

cd /path/to/your-recipe
npm link tjbot-ce

Tip

If you want to update your recipe to use the node-tjbotlib version from npmjs.com, you can unlink the local library via npm unlink --no-save tjbot-ce && npm install.

4. Keep the library healthy while you work

As you make changes within node-tjbotlib, run the standard quality checks -- formatting, linting, and testing -- before you open a pull request.

npm run format
npm run lint
npm run test

These task runners keep the code formatted consistently, catches style and correctness issues, and rebuilds and runs the test suite.

Python development

TJBot's Python workflow is centered around a local checkout of the python-tjbotlib library and linking it to your recipes.

1. Clone python-tjbotlib

TJBot's Python library is called python-tjbotlib. Create a fork of the python-tjbotlib repository and check it out locally. We recommend placing it under ~/.tjbot so it is easy to find and reuse across recipes.

mkdir -p ~/.tjbot
cd ~/.tjbot
git clone <your-fork-url-of-python-tjbotlib>
cd python-tjbotlib

2. Link a recipe to the local library

In directory of the recipe you want to work on, link the local tjbot package name to your checkout of python-tjbotlib.

cd /path/to/your-recipe
uv add --editable ~/.tjbot/python-tjbotlib

Tip

If you want to update your recipe to use the python-tjbotlib version from pypi.org, you can unlink the local library via uv add my_python_lib && uv sync.

3. Keep the library healthy while you work

As you make changes within python-tjbotlib, run the standard quality checks -- formatting, linting, and testing -- before you open a pull request.

mise run format
mise run lint
mise run test

These task runners keep the code formatted consistently, catches style and correctness issues, and rebuilds and runs the test suite.

Pull request guidance

Please keep pull requests focused and easy to review.

• Open or reference an issue before starting work, especially for larger changes.
• Keep the scope of each PR narrow when possible.
• Describe what changed, why it changed, and how you verified it.
• Include tests or explain why a test is not practical.
• Update documentation when the user-facing behavior changes.
• Avoid unrelated refactors in the same PR.
• Call out hardware requirements, setup changes, or migration steps in the PR description.

Commit messages and sign-off

Use clear commit messages that explain the change. Include a Signed-off-by line in your commit or PR description to satisfy the Developer Certificate of Origin (DCO).

Example:

Signed-off-by: Your Name <you@example.com>

Before you open a PR

Use this short checklist before you submit changes:

1. The code is formatted.
2. Lint passes.
3. Tests pass.
4. Documentation is updated if behavior changed.
5. The change is easy to review.
6. The PR description includes any setup or verification notes the reviewer needs.