From ae876b3b7dc3533ff59b0592c01b74aaf70e93d9 Mon Sep 17 00:00:00 2001 From: tdgao Date: Tue, 17 Mar 2026 22:12:21 -0600 Subject: [PATCH 1/4] docs: update contribution pages --- README.md | 6 +- .../src/content/docs/contributing/daedalus.md | 11 ++++ .../src/content/docs/contributing/docs.md | 2 +- .../docs/contributing/getting-started.md | 66 ++++++++++++++----- .../src/content/docs/contributing/knossos.md | 31 ++++----- .../src/content/docs/contributing/labrinth.md | 4 +- .../src/content/docs/contributing/minotaur.md | 2 + .../src/content/docs/contributing/theseus.md | 32 +++++---- 8 files changed, 103 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 74def556eb..f7c3730a79 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,10 @@ If you're not a developer and you've stumbled upon this repository, you can acce ## Development -This repository contains two primary packages. For detailed development information, please refer to their respective READMEs: +This repository contains two primary packages. For detailed development information, please refer to their respective guides: -- [Web Interface](apps/frontend/README.md) -- [Desktop App](apps/app/README.md) +- [Website frontend](https://docs.modrinth.com/contributing/knossos/) +- [Desktop app](https://docs.modrinth.com/contributing/theseus/) ## Contributing diff --git a/apps/docs/src/content/docs/contributing/daedalus.md b/apps/docs/src/content/docs/contributing/daedalus.md index 87aa4179dd..ea68831ac2 100644 --- a/apps/docs/src/content/docs/contributing/daedalus.md +++ b/apps/docs/src/content/docs/contributing/daedalus.md @@ -1,4 +1,15 @@ --- title: Daedalus (Metadata service) description: Guide for contributing to Modrinth's frontend +sidebar: + order: 5 --- + +Daedalus is a powerful tool which queries and generates metadata for the Minecraft (and other games in the future!) game +and mod loaders for: + +- Performance (Serving static files can be easily cached and is extremely quick) +- Ease for Launcher Devs (Metadata is served in an easy to query and use format) +- Reliability (Provides a versioning system which ensures no breakage with updates) + +Daedalus supports the original Minecraft data and reposting for the Forge, Fabric, Quilt, and NeoForge loaders. diff --git a/apps/docs/src/content/docs/contributing/docs.md b/apps/docs/src/content/docs/contributing/docs.md index fd0500ef93..09f238be09 100644 --- a/apps/docs/src/content/docs/contributing/docs.md +++ b/apps/docs/src/content/docs/contributing/docs.md @@ -17,7 +17,7 @@ pnpm run docs:dev When ready, you will have a hot-reloading environment of the docs site running on port 4321. -#### Ready to open a PR? +## Ready to open a PR? While there is no linting requirement on Docs, we do ask that you quickly check your writing before contributing. diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md index 28bec6a4ff..1b86352199 100644 --- a/apps/docs/src/content/docs/contributing/getting-started.md +++ b/apps/docs/src/content/docs/contributing/getting-started.md @@ -9,23 +9,7 @@ sidebar: Every public-facing aspect of Modrinth, including everything from our [API/backend][labrinth] and [frontend][knossos] to our [Gradle plugin][minotaur] and [launcher][theseus], is released under free and open source licenses on [GitHub]. As such, we love contributions from community members! Before proceeding to do so, though, there are a number of things you'll want to keep in mind throughout the process, as well as some details specific to certain projects. -## Things to keep in mind - -### Consult people on Discord - -There are a number of reasons to want to consult with people on our [Discord] before making a pull request. For example, if you're not sure whether something is a good idea or not, if you're not sure how to implement something, or if you can't get something working, these would all be good opportunities to create a thread in the `#development` forum channel. - -If you intend to work on new features, to make significant codebase changes, or to make UI/design changes, please open a discussion thread first to ensure your work is put to its best use. - -### Don't get discouraged - -At times, pull requests may be rejected or left unmerged for a variation of reasons. Don't take it personally, and don't get discouraged! Sometimes a contribution just isn't the right fit for the time, or it might have just been lost in the mess of other things to do. Remember, the core Modrinth team are often busy, whether it be on a specific project/task or on external factors such as offline responsibilities. It all falls back to the same thing: don't get discouraged! - -### Code isn't the only way to contribute - -You don't need to know how to program to contribute to Modrinth. Quality assurance, supporting the community, coming up with feature ideas, and making sure your voice is heard in public decisions are all great ways to contribute to Modrinth. If you find bugs, reporting them on the appropriate issue tracker is your responsibility; however, remember that potential security breaches and exploits must instead be reported in accordance with our [security policy](https://modrinth.com/legal/security). - -## Project-specific details +## Development If you wish to contribute code to a specific project, here's the place to start. Most of Modrinth is written in the [Rust language](https://www.rust-lang.org), but some things are written in other languages/frameworks like [Nuxt.js](https://nuxtjs.org) or Java. @@ -33,7 +17,7 @@ Most of Modrinth's code is in our monorepo, which you can find [here](https://gi Follow the project-specific instructions below to get started: -- [Knossos (frontend)](/contributing/knossos) +- [Knossos (Website frontend)](/contributing/knossos) - [Theseus (Modrinth App)](/contributing/theseus) - [Minotaur (Gradle plugin)](/contributing/minotaur) - [Labrinth (API/backend)](/contributing/labrinth) @@ -49,3 +33,49 @@ Follow the project-specific instructions below to get started: [docs]: https://github.com/modrinth/code/tree/main/apps/docs [Rust]: https://www.rust-lang.org/tools/install [pnpm]: https://pnpm.io + +## Contribution guidelines + +These guidelines apply to all Modrinth projects. Following them will help your contributions get reviewed and merged smoothly. + +### Keep pull requests small and focused + +We strongly encourage small, focused pull requests over large, sweeping changes. Bug fixes, QOL improvements, and other incremental contributions are much easier to review and more likely to be merged quickly. If you're looking for something to work on, check out the [GitHub issues](https://github.com/modrinth/code/issues) tab for open tasks and known bugs. + +### Reference issues in your pull request + +If your pull request fixes or relates to an existing issue, mention the issue number in your PR description (e.g., `Fixes #1234`). When applicable, include the issue number in your commit messages as well. This helps maintain traceability and automatically closes issues when PRs are merged. + +### Pull request titles + +Make sure the title starts with a semantic prefix: + +- **feat**: A new feature +- **fix**: A bug fix +- **docs**: Documentation only changes +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **perf**: A code change that improves performance +- **test**: Adding missing tests or correcting existing tests +- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) +- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) +- **chore**: Other changes that don't modify src or test files +- **revert**: Reverts a previous commit + +## Things to keep in mind + +Here are some tips and reminders to help you in your contribution. + +### Consult people on Discord + +There are a number of reasons to want to consult with people on our [Discord] before making a pull request. For example, if you're not sure whether something is a good idea or not, if you're not sure how to implement something, or if you can't get something working, these would all be good opportunities to create a thread in the `#development` forum channel. + +If you intend to work on new features, to make significant codebase changes, or to make UI/design changes, please open a discussion thread first to ensure your work is put to its best use. + +### Don't get discouraged + +At times, pull requests may be rejected or left unmerged for a variation of reasons. Don't take it personally, and don't get discouraged! Sometimes a contribution just isn't the right fit for the time, or it might have just been lost in the mess of other things to do. Remember, the core Modrinth team are often busy, whether it be on a specific project/task or on external factors such as offline responsibilities. It all falls back to the same thing: don't get discouraged! + +### Code isn't the only way to contribute + +You don't need to know how to program to contribute to Modrinth. Quality assurance, supporting the community, coming up with feature ideas, and making sure your voice is heard in public decisions are all great ways to contribute to Modrinth. If you find bugs, reporting them on the appropriate issue tracker is your responsibility; however, remember that potential security breaches and exploits must instead be reported in accordance with our [security policy](https://modrinth.com/legal/security). diff --git a/apps/docs/src/content/docs/contributing/knossos.md b/apps/docs/src/content/docs/contributing/knossos.md index ed166164b8..ad52268dc1 100644 --- a/apps/docs/src/content/docs/contributing/knossos.md +++ b/apps/docs/src/content/docs/contributing/knossos.md @@ -1,35 +1,32 @@ --- -title: Knossos (Frontend) +title: Knossos (Website frontend) description: Guide for contributing to Modrinth's frontend +sidebar: + order: 2 --- -This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/frontend` directory. +[Knossos] is the Nuxt.js frontend. You will need to install [pnpm] and run the standard commands: -[knossos] is the Nuxt.js frontend. You will need to install [pnpm] and run the standard commands: +## Setup -```bash -pnpm install -pnpm run web:dev -``` +### 1. Install prerequisites -Once that's done, you'll be serving knossos on `localhost:3000` with hot reloading. You can replace the `dev` in `pnpm run dev` with `build` to build for a production server and `start` to start the server. You can also use `pnpm run lint` to find any eslint problems, and `pnpm run fix` to try automatically fixing those problems. +- Install the package manager [pnpm](https://pnpm.io/) -
-.env variables & command line options +### 2. Install dependencies & set up .env -#### Basic configuration +- Clone [`https://github.com/modrinth/code`](https://github.com/modrinth/code) and run `pnpm install` in the workspace root folder. +- In `apps/frontend` you should be able to see `.env.prod`, `.env.staging` — for basic work, it's recommended to use `.env.prod`. Copy the relevant file into a new `.env` file within the `apps/frontend` folder. -`SITE_URL`: The URL of the site (used for auth redirects). Default: `http://localhost:3000` -`BASE_URL`: The base URL for the API. Default: `https://staging-api.modrinth.com/v2/` -`BROWSER_BASE_URL`: The base URL for the API used in the browser. Default: `https://staging-api.modrinth.com/v2/` +### 3. Run the frontend -
+- Run `pnpm web:dev` in the workspace root folder. Once that's done, you'll be serving knossos on `localhost:3000` with hot reloading. -#### Ready to open a PR? +## Ready to open a PR? If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria: -- `pnpm run fix` has been run. +- `pnpm prepr:frontend` has been run. [knossos]: https://github.com/modrinth/code/tree/main/apps/frontend [pnpm]: https://pnpm.io diff --git a/apps/docs/src/content/docs/contributing/labrinth.md b/apps/docs/src/content/docs/contributing/labrinth.md index 9fd1626ce7..9d48a89fab 100644 --- a/apps/docs/src/content/docs/contributing/labrinth.md +++ b/apps/docs/src/content/docs/contributing/labrinth.md @@ -1,6 +1,8 @@ --- title: Labrinth (API) description: Guide for contributing to Modrinth's backend +sidebar: + order: 4 --- This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/labrinth` directory. The instructions below assume that you have switched your working directory to the `apps/labrinth` subdirectory. @@ -89,7 +91,7 @@ The OAuth configuration options are fairly self-explanatory. For help setting up -#### Ready to open a PR? +## Ready to open a PR? If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria: diff --git a/apps/docs/src/content/docs/contributing/minotaur.md b/apps/docs/src/content/docs/contributing/minotaur.md index 130ca6879c..f2c87eee90 100644 --- a/apps/docs/src/content/docs/contributing/minotaur.md +++ b/apps/docs/src/content/docs/contributing/minotaur.md @@ -1,6 +1,8 @@ --- title: Minotaur (Gradle plugin) description: Guide for contributing to Modrinth's gradle plugin +sidebar: + order: 5 --- [Minotaur][minotaur] is the Gradle plugin used to automatically publish artifacts to Modrinth. To run your copy of the plugin in a project, publish it to your local Maven with `./gradlew publishToMavenLocal` and add `mavenLocal()` to your buildscript. diff --git a/apps/docs/src/content/docs/contributing/theseus.md b/apps/docs/src/content/docs/contributing/theseus.md index 1138f04a45..0cf2b74a6d 100644 --- a/apps/docs/src/content/docs/contributing/theseus.md +++ b/apps/docs/src/content/docs/contributing/theseus.md @@ -1,22 +1,32 @@ --- title: Theseus (Modrinth App) description: Guide for contributing to Modrinth's desktop app +sidebar: + order: 3 --- -This project is part of our [monorepo](https://github.com/modrinth/code). You can find it in the `apps/app` directory. +[Theseus] is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend. -[theseus] is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend. To get started, install [pnpm], [Rust], and the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for your system. Then, run the following commands: +## Setup -```bash -pnpm install -pnpm run app:dev -``` +### 1. Install prerequisites -Once the commands finish, you'll be viewing a Tauri window with Nuxt.js hot reloading. +- [pnpm](https://pnpm.io/) +- [Rust](https://www.rust-lang.org/tools/install) +- [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) -You can use `pnpm run lint` to find any eslint problems, and `pnpm run fix` to try automatically fixing those problems. +### 2. Install dependencies & set up .env -### Theseus Architecture +- Clone [`https://github.com/modrinth/code`](https://github.com/modrinth/code) and run `pnpm install` in the workspace root folder. +- In `packages/app-lib` you should be able to see `.env.prod`, `.env.staging` — for basic app work, it's recommended to use `.env.prod`. Copy the relevant file into a new `.env` file within the `packages/app-lib` folder. + +### 3. Run the app + +- Run `pnpm app:dev` in the workspace root folder. +- If you encounter an "Unable to initialise GTK" error on Linux, try running `pnpm run dev` within the `apps/app` folder rather than the workspace root command. If this doesn't work, use a VM with Windows and repeat these steps. +- If you get issues with being unable to find a display, and you're running the dev env inside a container (e.g. an Arch dev container on a non-Arch host), run `xhost +local:` to allow it to bind to an X11/Xwayland socket. + +## Theseus Architecture Theseus is split up into three parts: @@ -30,11 +40,11 @@ When running SQLX commands, be sure to set the `DATABASE_URL` environment variab You can edit the app's data directory using the `THESEUS_CONFIG_DIR` environment variable. -#### Ready to open a PR? +## Ready to open a PR? If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria: -- Run `pnpm run fix` to address any fixable issues automatically. +- Run `pnpm prepr:frontend` to address any fixable issues automatically. - Run `cargo fmt` to format Rust-related code. - Run `cargo clippy` to validate Rust-related code. - Run `cargo sqlx prepare --package theseus` if you've changed any SQL code to validate statements. From 9fe6067beac43236f20e3204fd81de1220ae4e70 Mon Sep 17 00:00:00 2001 From: tdgao Date: Tue, 17 Mar 2026 22:15:57 -0600 Subject: [PATCH 2/4] adjust pull request titles --- .../src/content/docs/contributing/getting-started.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md index 1b86352199..a65ff881c2 100644 --- a/apps/docs/src/content/docs/contributing/getting-started.md +++ b/apps/docs/src/content/docs/contributing/getting-started.md @@ -52,15 +52,16 @@ Make sure the title starts with a semantic prefix: - **feat**: A new feature - **fix**: A bug fix -- **docs**: Documentation only changes -- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- **devex**: Improves developer experience - **refactor**: A code change that neither fixes a bug nor adds a feature +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- **docs**: Documentation only changes +- **chore**: Other changes that don't modify src or test files +- **revert**: Reverts a previous commit - **perf**: A code change that improves performance - **test**: Adding missing tests or correcting existing tests - **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) - **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) -- **chore**: Other changes that don't modify src or test files -- **revert**: Reverts a previous commit ## Things to keep in mind From 9ef03c58f880ae5784bbbb6f49685c8afde3559b Mon Sep 17 00:00:00 2001 From: tdgao Date: Tue, 17 Mar 2026 22:18:21 -0600 Subject: [PATCH 3/4] update pull request description --- apps/docs/src/content/docs/contributing/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md index a65ff881c2..ee0df1120d 100644 --- a/apps/docs/src/content/docs/contributing/getting-started.md +++ b/apps/docs/src/content/docs/contributing/getting-started.md @@ -42,9 +42,9 @@ These guidelines apply to all Modrinth projects. Following them will help your c We strongly encourage small, focused pull requests over large, sweeping changes. Bug fixes, QOL improvements, and other incremental contributions are much easier to review and more likely to be merged quickly. If you're looking for something to work on, check out the [GitHub issues](https://github.com/modrinth/code/issues) tab for open tasks and known bugs. -### Reference issues in your pull request +### Pull request descriptions -If your pull request fixes or relates to an existing issue, mention the issue number in your PR description (e.g., `Fixes #1234`). When applicable, include the issue number in your commit messages as well. This helps maintain traceability and automatically closes issues when PRs are merged. +Every PR should include a clear description of what it does. Briefly explain what was added, updated, or fixed, and provide any relevant context for reviewers. If your PR fixes or relates to an existing issue, reference the issue number in the description (e.g., `Fixes #1234`) as this helps maintain traceability and automatically closes issues when the PR is merged. ### Pull request titles From 1fecba6b77b19921d444d3c7065aa1f3ddb90f71 Mon Sep 17 00:00:00 2001 From: tdgao Date: Wed, 18 Mar 2026 10:20:49 -0600 Subject: [PATCH 4/4] remove codenames for modrinth website and app --- .../docs/src/content/docs/contributing/getting-started.md | 4 ++-- apps/docs/src/content/docs/contributing/knossos.md | 8 ++++---- apps/docs/src/content/docs/contributing/theseus.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md index ee0df1120d..f8dea78811 100644 --- a/apps/docs/src/content/docs/contributing/getting-started.md +++ b/apps/docs/src/content/docs/contributing/getting-started.md @@ -17,8 +17,8 @@ Most of Modrinth's code is in our monorepo, which you can find [here](https://gi Follow the project-specific instructions below to get started: -- [Knossos (Website frontend)](/contributing/knossos) -- [Theseus (Modrinth App)](/contributing/theseus) +- [Modrinth Website](/contributing/knossos) +- [Modrinth App](/contributing/theseus) - [Minotaur (Gradle plugin)](/contributing/minotaur) - [Labrinth (API/backend)](/contributing/labrinth) - [Daedalus (Metadata service)](/contributing/daedalus) diff --git a/apps/docs/src/content/docs/contributing/knossos.md b/apps/docs/src/content/docs/contributing/knossos.md index ad52268dc1..efe79b9f59 100644 --- a/apps/docs/src/content/docs/contributing/knossos.md +++ b/apps/docs/src/content/docs/contributing/knossos.md @@ -1,11 +1,11 @@ --- -title: Knossos (Website frontend) +title: Modrinth Website description: Guide for contributing to Modrinth's frontend sidebar: order: 2 --- -[Knossos] is the Nuxt.js frontend. You will need to install [pnpm] and run the standard commands: +The [Modrinth Website], codename Knossos, is a Nuxt.js frontend. You will need to install [pnpm] and run the standard commands: ## Setup @@ -20,7 +20,7 @@ sidebar: ### 3. Run the frontend -- Run `pnpm web:dev` in the workspace root folder. Once that's done, you'll be serving knossos on `localhost:3000` with hot reloading. +- Run `pnpm web:dev` in the workspace root folder. Once that's done, you'll be serving the website on `localhost:3000` with hot reloading. ## Ready to open a PR? @@ -28,5 +28,5 @@ If you're prepared to contribute by submitting a pull request, ensure you have m - `pnpm prepr:frontend` has been run. -[knossos]: https://github.com/modrinth/code/tree/main/apps/frontend +[Modrinth website]: https://github.com/modrinth/code/tree/main/apps/frontend [pnpm]: https://pnpm.io diff --git a/apps/docs/src/content/docs/contributing/theseus.md b/apps/docs/src/content/docs/contributing/theseus.md index 0cf2b74a6d..090f58aaa3 100644 --- a/apps/docs/src/content/docs/contributing/theseus.md +++ b/apps/docs/src/content/docs/contributing/theseus.md @@ -1,11 +1,11 @@ --- -title: Theseus (Modrinth App) +title: Modrinth App description: Guide for contributing to Modrinth's desktop app sidebar: order: 3 --- -[Theseus] is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend. +The [Modrinth App], codename Theseus, is the Tauri-based launcher that lets users conveniently play any mod or modpack on Modrinth. It uses the Rust-based Tauri as the backend and Vue.js as the frontend. ## Setup @@ -49,6 +49,6 @@ If you're prepared to contribute by submitting a pull request, ensure you have m - Run `cargo clippy` to validate Rust-related code. - Run `cargo sqlx prepare --package theseus` if you've changed any SQL code to validate statements. -[theseus]: https://github.com/modrinth/code/tree/main/apps/app +[Modrinth App]: https://github.com/modrinth/code/tree/main/apps/app [Rust]: https://www.rust-lang.org/tools/install [pnpm]: https://pnpm.io