Repository navigation
Development
Generated from
CONTRIBUTING.mdat3f7e3ea3cab7. Edit the source, not this page -- the next merge to main overwrites any change here.
Thanks for wanting to contribute — small fixes and thoughtful larger changes are both very welcome.
AutoBot is a self-hosted AI platform. Contributions that make it faster, more reliable, or easier to deploy and extend are the highest priority.
- Pick one clear thing to fix or improve
- Touch the smallest possible number of files
- All tests pass and CI is green
- Fill out the PR template fully
These get reviewed quickly when they are clean and targeted.
Good candidates: bug fixes, documentation corrections, test coverage gaps, Docker/deployment improvements, small UI polish.
- Open an issue first — describe what you are trying to solve and your proposed approach
- Wait for feedback before writing code
- In your PR include:
- Before / after screenshots or a short video for any UI or behavior change
- Clear description of what changed and why
- Proof it works (manual testing notes, curl output, or test run)
- All tests passing and CI green
- PR template fully filled out
PRs that follow this path are much more likely to be accepted, even when they are large.
All PRs must target main, not release. Direct commits to release are blocked by a pre-commit hook.
<type>(scope): <description> (#issue-number)
Types: feat, fix, refactor, docs, test, chore
Example: fix(chat): prevent duplicate messages on reconnect (#1234)
Every pull request must follow .github/PULL_REQUEST_TEMPLATE.md. Required sections: Thinking Path, What Changed, Verification, Risks, and Checklist.
Run tests locally before pushing. CI must be green before a PR can be merged.
# Backend
cd autobot-backend && python -m pytest
# Frontend
cd autobot-frontend && npm run type-check && npm run lintNever bypass the pre-commit hook with --no-verify. If the hook blocks your commit, fix the underlying issue.
Every PR description must include a Thinking Path — a short chain of reasoning from the top of the project down to exactly what you changed. This replaces vague summaries with traceable logic.
- AutoBot lets users chat with their own documents using any LLM
- The chat session cache uses a hard-coded 24-hour Redis TTL
- Hard-coded TTLs cannot be tuned without redeploying, which breaks operator setups with custom retention policies
- So this PR replaces the hard-coded value with a module-level constant resolved from the
AUTOBOT_CHAT_SESSION_CACHE_TTLenv var, with a logged-fallback default of 24h- That way operators can tune retention without touching source code
After the Thinking Path, include: what you changed, why it matters, how to verify it, and any risks or known limitations. Screenshots if there is a visible change.
AutoBot's core feature roadmap is actively managed. Uncoordinated feature PRs may be closed even when the implementation is high quality — that is about roadmap coherence and long-term maintenance, not a judgement of your effort.
If you want to contribute a feature:
- Check open issues and GitHub Discussions first
- Open an issue to discuss the idea before writing code
- If the feature fits as a plugin, prefer building it that way
Bugs, documentation improvements, and small targeted fixes are the easiest path to getting merged — and genuinely appreciated.
- One PR = one logical change
- Keep commits focused and descriptive
- No commented-out code, no TODO comments — file a GitHub issue instead
- No
print()orconsole.log()— use the project logger (logging.getLogger(__name__)/createLogger('Name')) - If you find a bug while working on something else, open a new issue rather than fixing it inline
- Be kind in discussions
git clone https://github.com/mrveiss/AutoBot-AI.git
cd AutoBot-AI
cp .env.example .env
docker compose up -dVisit http://localhost — AutoBot is running.
For backend development without Docker:
cd autobot-backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8001For frontend development:
cd autobot-frontend
npm install
npm run devBefore your first commit, install pre-commit hooks to catch formatting and linting issues locally:
pip install pre-commit
pre-commit installHooks run automatically on each commit, checking Black formatting, isort, flake8, autoflake, mypy, and bandit. Fix any reported issues before committing again. The CI workflow (enforce-precommit.yml) validates these same checks on every PR.
pre-commit install is a separate step from bash scripts/install-git-hooks.sh, and both are needed. The installer copies AutoBot's own standalone pre-commit/pre-push hooks (the protected-branch guard, tools/git-hooks/); pre-commit install wires the framework hooks in .pre-commit-config.yaml. Both write .git/hooks/pre-commit, so whichever runs second replaces the other. Run the installer first and pre-commit install second, and re-run pre-commit install any time you re-run the installer. Then check what is actually installed rather than assuming:
cat .git/hooks/pre-commit # which of the two is in place
ls .git/hooks/pre-commit.legacy # what pre-commit displaced, if anythingThe protected-branch rule is enforced on the server regardless, so a displaced branch guard costs you a rejected push rather than a bad commit on release.
Not every hook's verdict carries the same weight in CI, and the split is deliberate. Formatter and linter findings are reported as warnings by enforce-precommit.yml; a hook that could not execute fails the job (#14181); and a behavioural hook — one whose entry is a test suite asserting shipped behaviour, currently ssot-config-lib-guard — fails the job on a finding (#14878), because there the finding is the regression.
New to the codebase? Start with issues tagged good-first-issue.
No code needed: each language is one JSON file, and every language issue is a good first issue (umbrella: #18768). English is the source. Any string a language lacks is shown in English, so a partial translation is always safe to merge.
-
Pick one section. Open your language's issue, choose one section from its table and comment with the section's name so nobody else takes it. To see what's left:
python3 scripts/list_untranslated.py --lang de # untranslated count per section python3 scripts/list_untranslated.py --lang de --section workflow # that section's keys and English text
-
Translate those keys in
autobot-frontend/src/i18n/locales/<lang>.json. If a key is missing there, copy it fromen.json. Keep every key name and every{placeholder}exactly as written, and don't editen.json. -
Open a PR titled
i18n(<lang>): translate <section>, withRefs #<your language's issue>. There is no count to update: CI compares your locale file with the base, and only fails if a string that had a translation lost it.
The SLM console reuses these translations automatically (scripts/lift_locale_translations.py). Never edit its locale files by hand.
Questions? Open an issue or start a Discussion. Happy hacking.