Contributing and reference12 of 12
Getting help, and reporting a problem
On this page
Four channels, and which one you want depends entirely on what kind of problem it is.
| Kind of problem | Where |
|---|---|
| Something does not work | a bug report issue |
| Something should be possible | a feature request issue |
| A security vulnerability | never a public issue — see below |
| Someone's behaviour | a conduct report — see below |
These are the channels the repository's own documents name. They are named here to match, not to extend: nothing on this page invents a mailbox, a chat server or a forum, because the repository has none.
Before you open anything
Run kotoba doctor. It names your platform, your Python, which extras are installed and which piece is
missing, and the bug report template says outright that most reports are answered by it.
Bug reports
Use the Bug report template. It asks five things, four of them required:
- What happened — what you did, what you expected, what you got instead.
- Which version — the output of
kotoba --version.doctordoes not name it from a clone. - What
kotoba doctorsays — the whole output. Redact nothing but secrets. - Where — the web app, the terminal, Discord, the voice call, installing, or something else.
- Anything the log said — from
~/.kotoba/cli.log, or the terminal the backend was running in.
Feature requests
Use the Feature request template. Its first field asks for the problem, not the solution, and the reason is written into it: the problem often has a shorter answer than the one imagined.
What helps most is the shape of the thing you were trying to do when you hit the wall — not the feature you designed to fix it.
Blank issues are enabled, so a question that fits neither template still has somewhere to go.
Security
Do not open a public issue for a security problem.
Two private routes, both named in SECURITY.md:
- The report form at kotoba.rodhnin.com/report.
- A GitHub security advisory, which stays private until a fix ships and keeps the report attached to the code.
Say what you did, what happened, and what you expected. A proof of concept helps and is not required.
Neither channel could be verified from the repository. Both are external services, and whether they are live is not a fact any file here records.
What the project commits to
| Stage | What SECURITY.md says to expect |
|---|---|
| First reply | within 14 days, saying whether it reproduces — usually much sooner |
| While it is open | you are told what is being done, and asked before anything is published |
| Disclosure | when the fix ships, or 90 days after the report, whichever comes first |
| Where | a published advisory on the repository, and a CVE where one is warranted |
| Credit | your name in the advisory, or none at all — your choice |
The 90 days is a ceiling, not a target. Ask for longer and it will be honoured; if the problem is already public, disclosure is immediate.
There is no bug bounty. It is a small project and there is no money in it.
Supported version: the latest release. Older versions get no backports — the fix is the upgrade.
In scope
Kotoba running as documented, on a machine you control: the backend, the terminal, the web UI, the Discord bot, and the packaged wheel.
Out of scope
Because they are the product working as designed and documented:
- Anything she does after you approve an approval card. The card is the boundary.
- Everything on the what does not protect you list in
SECURITY.md. - Ordinary commands under
KOTOBA_SANDBOX=docker, where the container is the boundary. - Exposing the backend to a network without setting a gate password.
- Third-party services she talks to — report those to the service.
Testing safely
Test against your own install. Do not test against anyone else's machine, and do not use a vulnerability to reach data that is not yours. A report made in good faith under those terms will be treated as help, not as an attack, and no legal action will be sought over it.
Conduct
The Code of Conduct is the Contributor Covenant 2.1, used under CC BY 4.0.
This project has no private mailbox, and a conduct report should not have to be made in public. So:
- To reach the maintainers privately, use the report form, or the GitHub security advisory form — it is labelled for security because that is what GitHub built it for, but it is the only private channel GitHub gives a project. Say at the top that it is a conduct report.
- If the person you are reporting is a maintainer, or you would rather it were handled outside this project entirely, use GitHub's own abuse reporting. It reaches GitHub staff, not the project.
Do not put names or details in a public issue.
The enforcement ladder is four rungs: a private written warning, a warning with consequences, a temporary ban, a permanent ban.
Documentation
The repository keeps its Markdown short and points at the documentation site for the long guides. In the repository itself:
| File | What it covers |
|---|---|
README.md | what Kotoba is, the quick start, the limitations |
docs/self-hosting.md | running it yourself |
docs/cli.md | the terminal client |
CONTRIBUTING.md | ways to contribute, the layout, the dev setup, the conventions |
SECURITY.md | what protects you, and what does not |
ROADMAP.md | what is next, and what is deliberately not planned |
CHANGELOG.md | what changed |
THIRD_PARTY_NOTICES.md | every third-party licence, including Live2D's |
If something in docs/ was unclear when you were setting Kotoba up, fixing it is listed in
CONTRIBUTING.md as a way to contribute.