Contributing

Contributing

Pull requests and issues are both welcome.

Report a bug or ask for something

From inside Kotatsu

Open Settings, then System, and under Help choose Send feedback. A sheet opens. Choose A problem, An idea or Something else, add an optional title and write what you want to say.

Include diagnostics is on by default, and the text is shown in the sheet so you can read it and edit it. It holds your Kotatsu version, your browser and window size, your layout, theme and message look, what kind of connection answers (a provider's name and model, but for a custom endpoint only its kind, not its address), and the last few page errors. It never holds your chats, character or persona names, or keys. Switch it off to leave it out.

Then choose Open on GitHub. A new issue opens in your browser with everything filled in, and nothing is sent until you press Submit there. You need a free GitHub account. Copy report copies the same text, if you would rather post it somewhere else. If the report is long, Kotatsu copies the diagnostics to your clipboard and asks you to paste them into the issue.

On GitHub

Open an issue. A bug report is easiest to act on when it has:

• The Kotatsu release you run, such as v0.4.0. The Releases list shows the numbers.
• Your system: Windows, macOS or Linux, and the browser you use.
• The steps that lead to the problem, in order, and what you expected to see instead.
• The exact text of any error message. On Windows, the Kotatsu window stays open after an error so you can copy it.
• For an extension problem, the extension's name and a link to it.
• For a theme problem, the output of npm run theme:check -- your-theme-name.

Leave out anything private. Do not paste API keys, and look over screenshots for names and file paths before you attach them.

Requests are welcome too. Say what you are trying to do, not only the feature you have in mind.

Send a pull request

Pull requests go to lumenastrum/kotatsu-public. Good candidates are bug fixes, documentation fixes, themes and extension compatibility fixes.

This repository is a release mirror. Kotatsu is developed in a private repository, and each release rebuilds this one from it, one commit per version. A change made only here would be overwritten by the next release, so a merged pull request takes two steps:

1. The maintainer reviews and merges your pull request on GitHub, so you are credited as its author.
2. The maintainer then carries the same change into the source repository with a Co-authored-by trailer naming you. It ships in the next release and stays.

Until the next release, the change is in the main branch here, but not in a release build.

Keep a pull request to one change, and explain what it fixes and how you checked it. For a large change, open an issue first so the idea can be discussed before you write it.

What a change must not break

Kotatsu makes two promises to the people who use it. A change that breaks either one will need rework before it can be merged.

• The extension contract. CONTRACT.md freezes the surface that extensions reach into. Additions are allowed. Removing or renaming anything on the list needs an explicit revision of that file.
• The data contract. docs/data-contract.md describes the on-disk data folder. A SillyTavern data/ folder must drop into Kotatsu unchanged, and stock SillyTavern must still be able to open it afterwards. Kotatsu may add to it. It never renames, restructures or drops anything.

Some design rules follow from those promises:

• The interface is Kotatsu's own code, and the provider registry stays close to upstream SillyTavern so that upstream provider updates still merge.
• Everything Kotatsu adds to the data folder lives in dot-folders, and can be rebuilt from your chat files.
• Themes are data and contain no code.

Run it from source

You need Node.js 20 or newer and git. See Installing Kotatsu for the commands that start Kotatsu from a clone.

Before you open a pull request, run npm run lint. If you changed a theme, also run npm run theme:check -- your-theme-name. The theme authoring guide explains the check's output.

License

Kotatsu is licensed under AGPL-3.0, the same license as SillyTavern. By sending a pull request you agree that your change is released under it.