Skip to content

Contributing

This section is for people who change Kosatka itself: its core, its bundled modules and themes, its scripts and its documentation. If you build a site, start with the guides. If you write a theme or a module for your own site, see Themes and Modules: neither needs changes to the engine.

The process in full (issues, pull requests, code style, the licence) is in the repository’s CONTRIBUTING.md.

Kosatka is a CMS for any site, not the code of one site. Go code, templates and JavaScript hold no site’s content types, fields, URL paths, sections, block names, texts, IDs or slugs.

  • Whatever is specific to a site lives in its data: the database, the settings made in the admin, a data migration or config/*.yaml. Its look lives in its theme.
  • When one type or section needs a behaviour, build a general mechanism for it: a setting, a flag, a field type, a block plugin. Never write if type == "articles".
  • If you find site data hardcoded next to your change, don’t copy it: propose moving it into data.

Run a local site in Docker (Run in Docker) or build it from source (Run from source). The database tests and the migration generator need Docker either way.

Terminal window
./scripts/check.sh # golangci-lint (gofmt, go vet and the rest; the CI
# version, installed when missing), the unit tests,
# govulncheck and gitleaks when installed, the example
# module and site in examples/
./scripts/check.sh -race # the unit tests with the race detector (as CI)
./scripts/check.sh -db # plus the tests on MySQL and PostgreSQL and the
# migration files against the ent schemas (Docker)
./scripts/docs.sh # builds this documentation; a link to a missing
# page fails the build

./scripts/docs.sh dev serves the documentation at http://localhost:4321/kosatka/ and rebuilds it as docs/ changes. Both run in Docker when Node.js isn’t installed. Testing describes the tests and how to run part of them.

  • For anything bigger than a small fix, open an issue first: describe the problem and the approach.
  • One pull request holds one change. Describe it and say how you checked it.
  • Commit messages are in English: a short summary line, then what changed and why.
  • A change to how something works updates the matching page of this documentation in the same pull request. A new mechanism gets its description there too: in Architecture or Database and migrations for the engine’s insides, in the guides, themes or modules pages for what site builders and authors use.
  • Pages start with front matter holding their title and have no # heading of their own. Link pages by their files, relatively ([Views](../guides/views.md)).
  • Architecture: the layers, the request path, the core and the modules.
  • Database and migrations: the ent schemas, generated migrations, data steps, MySQL and PostgreSQL.
  • Testing: the kinds of tests, their file names, running them, the checks of the whole repository.
  • Demo sets: a whole demo site as data, installed with app install -demo-set.
  • Releasing: a vX.Y.Z tag and what the release workflow builds - the archives, the GitHub release, the Docker image.

Theme authors look in Themes, module authors in Modules and the module SDK.