Development Guide¶

Question

Please help us translate KS, either by contributing missing translations or reviewing the existing entries.

Introduction¶

The script is written in TypeScript. The JS userscript itself is not intended to be edited. Changes need to be made in the userscript source code and then be compiled into the actual userscript.

Prerequisites¶

The development environment is expected to be a POSIX-compliant system. On Windows, WSL will do fine.

You will need NodeJS to be able to work with the project. The project uses yarn as a package manager, which is usually integrated with recent NodeJS versions.

Additionally, you will need to have Docker available, to use the container-based Kittens Game development server. Other container runtimes work just as well.

General Development¶

Whenever you want to see the result of your changes, use:

make build

This will build a fresh version of the userscript. If you are running a development container, this build output will also be used the next time you refresh the page.

Development with Kittens Game Container¶

The development container provides a version of Kittens Game that already a Kitten Scientists version injected into it, based on your local development state.

See the dedicated documentation for more information.

Development without Container¶

To develop without containers, you can build a development version of the userscript with full debugging information.

make build

The userscript is placed in the output directory.

Type-Checking¶

Run make lint on the command line.

Commit Standards¶

KS development follows the Conventional Commits specification for commit messages.

Whenever possible, use one of the established scopes:

Tab related:

bonfire
religion
science
space
time
trade
village
workshop

Internals related:

api

Relates to the global kittenScientists API.
build

Relates to the process of producing one of the KS release fragment.
container

Relates to the KS development container.
core

Relates to central behavior of KS. Also includes state management.
filters

Relates to the log filters of KS.
i18n

Relates to translations of KS.
settings

Relates to changes to the settings system.
ui

Relates to the KS user interface.

Pull Requests¶

When you open a pull request, make sure that you squash your commits into a single one, unless individual commits are substantial enough that they should be preserved as-is. Just make sure that all commits follow the commit standards mentioned above.

Releasing a New Version¶

Have your release notes ready. You can draft them in the CHANGELOG.md and copy the auto-generated changes for the release from the GitHub release later.
Build a preview of the script:
```
make build
```
Load the built preview into a userscript manager in Chrome and perform a quick, manual test.
1. Does the script load at all?
2. Are settings restored to expectation?
3. Are settings saved when they are changed?
Last checks!
1. Does anything need to be committed?
2. Are all remote changes merged?
3. Did make pretty run one last time?

Create a tag for this version:

git tag -s v2.0.0-beta.12 -m "2.0.0-beta.12"

Push the tag:
```
git push origin v2.0.0-beta.12
```
Edit the drafted release on GitHub. Leave it drafted. Publish it when all release tasks listed here have been completed.
Raise the version number in package.json to a higher version that will be in development next!
Update the README.md to point the latest stable release.
Update the docs/current/docs/installation/index.md to point to the latest version number.
Update the .github/ISSUE_TEMPLATE/bug_report.yml to mention the latest version number.
Ultimately, search the entire project code base for the previous version string, like 2.0.0-beta.11. Make sure to also search for beta.11, beta11, and references to future releases that need to point to the new future release!
Run make docs, and create a new version with the final docs in docs/v2.0.0-beta.12.
There are other hardcoded version references in infrastructure and action-release-info. Those must be updated as well, and the entire changeset needs to be cycled through the deployment chain!

Note

Don't forget to publish the drafted release on GitHub!