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 shared node-tjbotlib library and one or more recipe repositories that depend on it.

1. Clone node-tjbotlib

TJBot's Node.js library is called node-tjbotlib and is implemented in Typescript. Create a fork 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

If you are creating a new recipe, link it the same way before you start wiring code together. If you are updating an existing recipe, relink it whenever you want it to use your current local changes in node-tjbotlib.

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

TBD

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.