Skip to content

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.

The project is set up to be used with Visual Studio Code. While other editors will work fine, some integrations have been prepared to make the development process easier.

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 and project 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.

General Development

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

yarn kitten-scientists: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.

When the container is built, it downloads the latest version of the game from https://github.com/nuclear-unicorn/kittensgame.

  1. Manual Refresh (recommended)

    Build the development container and start it.

    yarn devcontainer:run

    The script prints the URL where you can now play the game with KS installed.

    You will need to manually reload the page after each build to get the latest changes in the browser.

  2. Watcher (experimental)

    Start a watcher to continuously rebuild KS when you make code changes.

    yarn kitten-scientists:watch

    Danger

    Sadly, this behavior is known to produce broken output files. Use at your own risk and switch to manual builds as necessary.

If you ever want to rebuild the container from scratch, for example, to pull in the latest source code of KG again, run:

yarn devcontainer:rebuild

Kittens Game Branch

You can run the development container on another branch of Kittens Game by providing the branch name to the devcontainer commands, like so:

yarn devcontainer:run dev/alpha

Development without Container

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

  1. Run the build script.

    yarn kitten-scientists:preview

    The userscript is placed in the packages/kitten-scientists/output directory.

Type-Checking

To fill the Problems panel in VS Code with all current, type-related errors, run the typecheck:all npm task in VS Code.

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.

Releases

Building a Release Version of the Userscript

Run the script to build the release:

yarn kitten-scientists:release

Releasing a New Version

  1. 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.

  2. Build a preview of the script:

    yarn kitten-scientists:preview

  3. 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?

  4. Create a tag for this version:

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

  5. Push the tag:

    git push --tags

  6. Edit the drafted release on GitHub. Leave it drafted. Publish it when all release tasks have been completed.

  7. Raise the version number in package.json to a higher version that will be in development next!

  8. Update the README.md to point the latest stable release.

  9. Update the docs/current/docs/installation/quick-start.md to point to the latest version number.

  10. Update the .github/ISSUE_TEMPLATE/bug_report.yml to mention the latest version number.

  11. Ultimately, search the entire project code base for the previous version string, like 2.0.0-beta.10. Make sure to also search for beta.10, beta10, and references to future releases that need to point to the new future release!

Note

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