Skip to content

Commit 0307d28

Browse files
mworzalamworzala
committed
chore: add license, readme, contributing
1 parent 9f2cf82 commit 0307d28

File tree

3 files changed

+94
-45
lines changed

3 files changed

+94
-45
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributing
2+
3+
Thanks for your interest in contributing! This document covers the basics you need to know before opening a pull
4+
request.
5+
6+
## Getting Started
7+
8+
See [Development Setup](../.github/DEVELOPMENT_SETUP.md) for instructions on building and running the project locally.
9+
10+
## Before You Contribute
11+
12+
All contributors must sign our Contributor License Agreement.
13+
You'll be automatically prompted by CLA Assistant when you open your first pull request.
14+
15+
## Pull Requests
16+
17+
- Please open and issue or discuss on Discord before opening a PR (even for bug fixes).
18+
This helps ensure that your contribution is aligned with our goals and avoids duplicate/wasted effort.
19+
- Keep PRs relatively focused on a single change. Smaller PRs are easier to review and more likely to be merged quickly.
20+
- Follow go formatting conventions. Please avoid PRs that only change formatting or style.
21+
- We don't have a set review period, please be patient while we review.
22+
23+
## DB Schema Evolution
24+
25+
We use [golang-migrate/migrate](https://github.com/golang-migrate/migrate) for postgres schema migrations.
26+
27+
To create a new migration (**replace `<migration_name>` with a descriptive name**, and choose a directory):
28+
29+
```shell
30+
go tool migrate create -ext sql -dir internal/(db|playerdb|mapdb)/storage/migrate -seq <migration_name>
31+
```
32+
33+
Read through the [migrate best practices](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md) before
34+
writing migrations. Migrations must be idempotent, transactional, and backwards compatible. Never edit a migration that
35+
has already been deployed. We do not use down migrations currently.
36+
37+
DB changes must always be at least one version backwards compatible to support rolling updates.
38+
39+
> **Note on Tilt:** The service auto-restarts when you run `migrate` commands, which applies the migration
40+
> automatically. Disable the Tilt resource while writing a migration, then re-enable it once done.
41+
42+
## Communication
43+
44+
For questions, discussion, or if you're unsure whether a change would be welcome, please ask in the`#general-dev`
45+
channel in our [Discord](https://discord.hollowcube.net).

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Hollow Cube LLC
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 28 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,41 @@
1-
# Session Service
1+
# API Server
22

3-
The session service is responsible for keeping track of all players currently online (network wide in the future, but
4-
for now just mapmaker).
3+
The backend service for [Hollow Cube](https://hollowcube.net) — a Minecraft server for creative map building.
4+
This accompanies the [mapmaker](https://github.com/hollow-cube/mapmaker) game server repo.
55

6-
## Session Tracking
7-
The session service needs to keep a record (in redis for now) of every online player, and remove them when they
8-
disconnect.
6+
## Project Structure
97

10-
The Java server (proxy in the future) handles this by sending requests to the create and delete session endpoints:
11-
- `POST /session/{playerId}` (on join)
12-
- `DELETE /session/{playerId}` (on leave)
8+
- `api/`
9+
- `v1Public/` - Current-version public API for game data
10+
- `v4Internal/` - Current-version API for the game servers
11+
- `external/` - Incoming webhook endpoints for external services (eg Discord, Tebex)
12+
- `posthog/` - Caching PostHog feature flag proxy
13+
- `mapsV3/` - (deprecated) `map-service` api, in-progress migration to `v4Internal`
14+
- `v2/` - (deprecated) `player-service` api, in-progress migration to `v4Internal`
15+
- `v3/` - (deprecated) `session-service` api, in-progress migration to `v4Internal`
16+
- `auth/` - (deprecated) Envoy auth middleware
1317

14-
This works fine in the happy case, but we need to handle a case where the Minecraft server crashes unexpectedly,
15-
it would be problematic if the session service still thought the player was online. This is handled by the session
16-
service server tracking, see below.
18+
*Note: Historically this project was made up of 3 distinct services (`map-service`, `player-service`,
19+
`session-service`) so you may see references to those. They have since been merged but there remains
20+
some legacy separation.*
1721

18-
## Server Tracking
19-
The session service needs to keep a record (in redis for now) of every running backend server to be able to route
20-
players to the correct server, as well as know when a server goes down (incl. unexpected crashes). To accomplish this,
21-
the session service uses the Kubernetes client API to watch for changes to the server state. There is a single instance
22-
of the session service selected at any given moment to track the server state. This is done using the Kubernetes client
23-
leadership election API.
22+
## Getting Started
2423

25-
The leader instance of the session service will watch for changes and update the server state in redis. Any service
26-
instance (including the leader) may query the server state when assigning players.
24+
See [Development Setup](https://github.com/hollow-cube/map-maker/blob/main/.github/DEVELOPMENT_SETUP.md) for
25+
instructions on running the project locally.
2726

28-
## Chat
29-
Chat is handled by the session service also. Chat is done over Kafka. TODO write more
27+
## Contributing
3028

31-
## Local Development
32-
You must have the following installed:
33-
- goimports: `go install golang.org/x/tools/cmd/goimports@latest`
34-
- [openapi-go](https://github.com/mworzala/openapi-go): `go install github.com/mworzala/openapi-go@latest`
29+
Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before opening a pull request.
3530

36-
You should use our Tilt setup to run the service locally, see [here](https://github.com/hollow-cube/development).
31+
All contributors must sign our
32+
[Contributor License Agreement](https://hollowcube.net/legal/individual-contributor-license-agreement).
33+
You'll be prompted automatically on your first PR.
3734

38-
## DB Schema Evolution
39-
We use [golang-migrate/migrate](https://github.com/golang-migrate/migrate) to handle postgres schema upgrades.
35+
## Community
4036

41-
To create a new migration, run the following command (**make sure to replace <migration_name> with a reasonable name**):
37+
We have a dedicated `#general-dev` channel in our [Discord](https://discord.hollowcube.net) for related questions.
4238

43-
```shell
44-
go tool migrate create -ext sql -dir internal/pkg/storage/migrate -seq <migration_name>
45-
```
39+
## License
4640

47-
Before writing any migrations, make sure to read through the best practices in the
48-
[migrate documentation](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md). In
49-
particular, migrations should always be idempotent, transactional and reversible. It is almost never
50-
valid to edit an existing migration after it has been deployed.
51-
52-
DB changes must always be (at least) single version backwards compatible to allow for rolling updates.
53-
54-
> **Note on using Tilt:**
55-
>
56-
> If you are using Tilt then the service will autorestart when you run `migrate` commands, which will
57-
> result in the migration being automatically applied. You should disable the tilt resource while editing
58-
> then reenable it after the migration is written.
41+
The code in this repository is licensed under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)