Contributing

By the end of this page you will have Osmium building and its tests passing on your machine, and you will know what a pull request has to satisfy before it is opened.

Prerequisites#

Go 1.25 or newer.
git and make.
golangci-lint, for make lint. Its configuration is in .golangci.yml.
gofumpt and goimports, for make fmt.
Java, if you intend to run a server rather than only build the binary.

Get it running#

bash

$ git clone https://github.com/limelamp/osmium.git
$ cd osmium
$ make            # lists every target
$ make run        # go run .
$ make test       # go test ./...

make build puts a stamped binary in ./bin/osmium; make install puts it in $(go env GOPATH)/bin. make snapshot builds the release artefacts locally without tagging anything.

Repository layout#

Path	What is in it
`cmd/`	The command line, one file per command
`internal/build/`	What the binary knows about itself: version, commit, build date
`internal/config/`	`config.json`, `osmium.json` and `osmium.lock`
`internal/scope/`	Where an operation runs, and where its output goes
`internal/shared/`	Modrinth, migration, player records
`internal/supervisor/`	The detached process that owns a running server
`internal/util/`	Downloading and installing server software
`internal/tui/`	The interface
`internal/tui/core/`	Layout, lists, scrolling, messages, fields, tickers
`internal/tui/styles/`	Containers, rows, hints, logs, progress bars
`internal/tui/components/`	The panels
`internal/tui/pages/`	The screens

The interface and the command line share their work: the create and migrate wizards run the very same steps in both, so a change to a step changes both at once.

Before you open a pull request#

bash

$ make lint test

Both must pass. make fmt runs gofumpt and goimports; make tidy and make vet are there too.

Commit messages are read by the release tooling, which groups them into the changelog by prefix: feat becomes Features, fix becomes Fixes, and everything else falls under Other. docs:, test: and chore: commits are left out of the changelog entirely.

Pull requests are welcome. Keep one change per pull request, and say in the description what a reviewer should try.

What is most wanted#

See the good first issue and help wanted labels on the repository. They are kept current; a list here would not be.

Filing a good bug report#

Open it at github.com/limelamp/osmium/issues and include:

The output of osmium --version in full — it carries the version, the commit, the build date, the Go toolchain and the platform.
Your OS and terminal, and the terminal's size if the problem is a drawing one.
The exact command you ran, or the sequence of keys in the interface.
What you expected and what happened instead. Paste the output rather than describing it.
The server's osmium.json, when the problem involves a server. Redact the paths if they say more about your machine than you want to share — the loader, version and the mod list are the parts that matter.
osmium doctor output, when the problem is a server that will not start.

For a crash, the whole panic including the stack trace is the useful part.

Code of conduct and licence#

Osmium follows the Contributor Covenant, version 2.1. It applies in the repository, in issues and pull requests, and anywhere someone is representing the project.

Osmium is free software under the GNU General Public License v3.0. Contributions are accepted under the same licence.