diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs index bbeee7cd5..a311a155f 100644 --- a/apps/docs/astro.config.mjs +++ b/apps/docs/astro.config.mjs @@ -40,15 +40,8 @@ export default defineConfig({ ], sidebar: [ { - label: 'Guides', - items: [ - // Each item here is one entry in the navigation menu. - { label: 'Example Guide', slug: 'guides/example' }, - ], - }, - { - label: 'Reference', - autogenerate: { directory: 'reference' }, + label: 'Contributing to Modrinth', + autogenerate: { directory: 'contributing' }, }, // Add the generated sidebar group to the sidebar. ...openAPISidebarGroups, diff --git a/apps/docs/src/content/docs/contributing/daedalus.md b/apps/docs/src/content/docs/contributing/daedalus.md new file mode 100644 index 000000000..87aa4179d --- /dev/null +++ b/apps/docs/src/content/docs/contributing/daedalus.md @@ -0,0 +1,4 @@ +--- +title: Daedalus (Metadata service) +description: Guide for contributing to Modrinth's frontend +--- diff --git a/apps/docs/src/content/docs/contributing/getting-started.md b/apps/docs/src/content/docs/contributing/getting-started.md new file mode 100644 index 000000000..de9772cf2 --- /dev/null +++ b/apps/docs/src/content/docs/contributing/getting-started.md @@ -0,0 +1,52 @@ +--- +title: Getting started +description: How can I contribute to Modrinth? +sidebar: + order: 1 +--- + +# Contributing to Modrinth + +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 + +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. + +Most of Modrinth's code is in our monorepo, which you can find [here](https://github.com/modrinth/code). Our monorepo is powered by [Turborepo](https://turborepo.org). + +Follow the project-specific instructions below to get started: +- [Knossos (frontend)](/contributing/knossos) +- [Theseus (Modrinth App)](/contributing/theseus) +- [Minotaur (Gradle plugin)](/contributing/minotaur) +- [Labrinth (API/backend)](/contributing/labrinth) +- [Daedalus (Metadata service)](/contributing/daedalus) + +### Documentation + +The [documentation](https://github.com/modrinth/docs) (which you are reading right now!) is the place to find any and all general information about Modrinth and its API. The instructions are largely the same as [knossos](#knossos-frontend), except that the docs have no lint. + +[Discord]: https://discord.modrinth.com +[GitHub]: https://github.com/modrinth +[knossos]: https://github.com/modrinth/code/tree/main/apps/frontend +[labrinth]: https://github.com/modrinth/labrinth +[theseus]: https://github.com/modrinth/theseus +[minotaur]: https://github.com/modrinth/minotaur +[Rust]: https://www.rust-lang.org/tools/install +[pnpm]: https://pnpm.io \ No newline at end of file diff --git a/apps/docs/src/content/docs/contributing/knossos.md b/apps/docs/src/content/docs/contributing/knossos.md new file mode 100644 index 000000000..4f9aecd20 --- /dev/null +++ b/apps/docs/src/content/docs/contributing/knossos.md @@ -0,0 +1,35 @@ +--- +title: Knossos (Frontend) +description: Guide for contributing to Modrinth's frontend +--- + +This project is our [monorepo](https://github.com/modrinth/code). You can find the frontend in the `apps/frontend` directory. + +[knossos] is the Nuxt.js frontend. You will need to install [pnpm] and run the standard commands: + +```bash +pnpm install +pnpm run web:dev +``` + +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. + +
+.env variables & command line options + +#### Basic configuration + +`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/` + +
+ +#### 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. + +[knossos]: https://github.com/modrinth/code/tree/main/apps/frontend +[pnpm]: https://pnpm.io \ No newline at end of file diff --git a/apps/docs/src/content/docs/contributing/labrinth.md b/apps/docs/src/content/docs/contributing/labrinth.md new file mode 100644 index 000000000..a95c389b0 --- /dev/null +++ b/apps/docs/src/content/docs/contributing/labrinth.md @@ -0,0 +1,115 @@ +--- +title: Labrinth (API) +description: Guide for contributing to Modrinth's backend +--- + + +[labrinth] is the Rust-based backend serving Modrinth's API with the help of the [Actix](https://actix.rs) framework. To get started with a labrinth instance, install docker, docker-compose (which comes with Docker), and [Rust]. The initial startup can be done simply with the command `docker-compose up`, or with `docker compose up` (Compose V2 and later). That will deploy a PostgreSQL database on port 5432 and a MeiliSearch instance on port 7700. To run the API itself, you'll need to use the `cargo run` command, this will deploy the API on port 8000. + +Now, you'll have to install the sqlx CLI, which can be done with cargo: + +```bash +cargo install --git https://github.com/launchbadge/sqlx sqlx-cli --no-default-features --features postgres,rustls +``` + +From there, you can create the database and perform all database migrations with one simple command: + +```bash +sqlx database setup +``` + +Finally, if on Linux, you will need the OpenSSL library. On Debian-based systems, this involves the `pkg-config` and `libssl-dev` packages. + +To enable labrinth to create a project, you need to add two things. + +1. An entry in the `loaders` table. +2. An entry in the `loaders_project_types` table. + +A minimal setup can be done from the command line with [psql](https://www.postgresql.org/docs/current/app-psql.html): + +```bash +psql --host=localhost --port=5432 -U -W +``` + +The default password for the database is `labrinth`. Once you've connected, run + +```sql +INSERT INTO loaders VALUES (0, 'placeholder_loader'); +INSERT INTO loaders_project_types VALUES (0, 1); -- modloader id, supported type id +INSERT INTO categories VALUES (0, 'placeholder_category', 1); -- category id, category, project type id +``` + +This will initialize your database with a modloader called 'placeholder_loader', with id 0, and marked as supporting mods only. It will also create a category called 'placeholder_category' that is marked as supporting mods only +If you would like 'placeholder_loader' to be marked as supporting modpacks too, run + +```sql +INSERT INTO loaders_project_types VALUES (0, 2); -- modloader id, supported type id +``` + +If you would like 'placeholder_category' to be marked as supporting modpacks too, run + +```sql +INSERT INTO categories VALUES (0, 'placeholder_category', 2); -- modloader id, supported type id +``` + +The majority of configuration is done at runtime using [dotenvy](https://crates.io/crates/dotenvy) and the `.env` file. Each of the variables and what they do can be found in the dropdown below. Additionally, there are three command line options that can be used to specify to MeiliSearch what you want to do. + +
+.env variables & command line options + +#### Basic configuration + +`DEBUG`: Whether debugging tools should be enabled +`RUST_LOG`: Specifies what information to log, from rust's [`env-logger`](https://github.com/env-logger-rs/env_logger); a reasonable default is `info,sqlx::query=warn` +`SITE_URL`: The main URL to be used for CORS +`CDN_URL`: The publicly accessible base URL for files uploaded to the CDN +`MODERATION_DISCORD_WEBHOOK`: The URL for a Discord webhook where projects pending approval will be sent +`CLOUDFLARE_INTEGRATION`: Whether labrinth should integrate with Cloudflare's spam protection +`DATABASE_URL`: The URL for the PostgreSQL database +`DATABASE_MIN_CONNECTIONS`: The minimum number of concurrent connections allowed to the database at the same time +`DATABASE_MAX_CONNECTIONS`: The maximum number of concurrent connections allowed to the database at the same time +`MEILISEARCH_ADDR`: The URL for the MeiliSearch instance used for search +`MEILISEARCH_KEY`: The name that MeiliSearch is given +`BIND_ADDR`: The bind address for the server. Supports both IPv4 and IPv6 +`MOCK_FILE_PATH`: The path used to store uploaded files; this has no default value and will panic if unspecified + +#### CDN options + +`STORAGE_BACKEND`: Controls what storage backend is used. This can be either `local`, `backblaze`, or `s3`, but defaults to `local` + +The Backblaze and S3 configuration options are fairly self-explanatory in name, so here's simply their names: +`BACKBLAZE_KEY_ID`, `BACKBLAZE_KEY`, `BACKBLAZE_BUCKET_ID` +`S3_ACCESS_TOKEN`, `S3_SECRET`, `S3_URL`, `S3_REGION`, `S3_BUCKET_NAME` + +#### Search, OAuth, and miscellaneous options + +`LOCAL_INDEX_INTERVAL`: The interval, in seconds, at which the local database is reindexed for searching. Defaults to `3600` seconds (1 hour). +`VERSION_INDEX_INTERVAL`: The interval, in seconds, at which versions are reindexed for searching. Defaults to `1800` seconds (30 minutes). + +The OAuth configuration options are fairly self-explanatory. For help setting up authentication, please contact us on [Discord]. + +`RATE_LIMIT_IGNORE_IPS`: An array of IPs that should have a lower rate limit factor. This can be useful for allowing the front-end to have a lower rate limit to prevent accidental timeouts. + +#### Command line options + +`--skip-first-index`: Skips indexing the local database on startup. This is useful to prevent doing unnecessary work when frequently restarting. +`--reconfigure-indices`: Resets the MeiliSearch settings for the search indices and exits. +`--reset-indices`: Resets the MeiliSearch indices and exits; this clears all previously indexed mods. + +
+ +#### Ready to open a PR? + +If you're prepared to contribute by submitting a pull request, ensure you have met the following criteria: + +- `cargo fmt` has been run. +- `cargo clippy` has been run. +- `cargo check` has been run. +- `cargo sqlx prepare` has been run. + +> Note: If you encounter issues with `sqlx` saying 'no queries found' after running `cargo sqlx prepare`, you may need to ensure the installed version of `sqlx-cli` matches the current version of `sqlx` used [in labrinth](https://github.com/modrinth/labrinth/blob/master/Cargo.toml). + +[Discord]: https://discord.modrinth.com +[GitHub]: https://github.com/modrinth +[labrinth]: https://github.com/modrinth/labrinth +[Rust]: https://www.rust-lang.org/tools/install diff --git a/apps/docs/src/content/docs/contributing/minotaur.md b/apps/docs/src/content/docs/contributing/minotaur.md new file mode 100644 index 000000000..19df6504b --- /dev/null +++ b/apps/docs/src/content/docs/contributing/minotaur.md @@ -0,0 +1,10 @@ +--- +title: Minotaur (Gradle plugin) +description: Guide for contributing to Modrinth's gradle plugin +--- + +[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. + +Minotaur contains two test environments within it - one with ForgeGradle and one with Fabric Loom. You may tweak with these environments to test whatever you may be trying; just make sure that the `modrinth` task within each still functions properly. GitHub Actions will validate this if you're making a pull request, so you may want to use [`act pull_request`](https://github.com/nektos/act) to test them locally. + +[minotaur]: https://github.com/modrinth/minotaur \ No newline at end of file diff --git a/apps/docs/src/content/docs/contributing/theseus.md b/apps/docs/src/content/docs/contributing/theseus.md new file mode 100644 index 000000000..79635bedc --- /dev/null +++ b/apps/docs/src/content/docs/contributing/theseus.md @@ -0,0 +1,43 @@ +--- +title: Theseus (Modrinth App) +description: Guide for contributing to Modrinth's desktop app +--- + +This project is our [monorepo](https://github.com/modrinth/code). + +[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: + +```bash +pnpm install +pnpm run app:dev +``` + +Once the commands finish, you'll be viewing a Tauri window with Nuxt.js hot reloading. + +You can use `pnpm run lint` to find any eslint problems, and `pnpm run fix` to try automatically fixing those problems. + +### Theseus Architecture + +Theseus is split up into three parts: +- `apps/app-frontend`: The Vue.JS frontend for the app +- `packages/app-lib`: The library holding all the core logic for the desktop app +- `apps/app`: The Tauri-based Rust app. This primarily wraps around the library with some additional logic for Tauri. + +The app's internal database is stored in SQLite. For production builds, this is found at /app.db. + +When running SQLX commands, be sure to set the `DATABASE_URL` environment variable to the path of the database. + +You can edit the app's data directory using the `THESEUS_CONFIG_DIR` environment variable. + +#### 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 `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. + +[theseus]: https://github.com/modrinth/code/tree/main/apps/app +[Rust]: https://www.rust-lang.org/tools/install +[pnpm]: https://pnpm.io \ No newline at end of file diff --git a/apps/docs/src/content/docs/guides/example.md b/apps/docs/src/content/docs/guides/example.md deleted file mode 100644 index ebd0f3bc7..000000000 --- a/apps/docs/src/content/docs/guides/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Guide -description: A guide in my new Starlight docs site. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx index fcd60e762..2bd953204 100644 --- a/apps/docs/src/content/docs/index.mdx +++ b/apps/docs/src/content/docs/index.mdx @@ -1,34 +1,15 @@ --- -title: Welcome to docs! -description: Get started building your docs site with Starlight. +title: Modrinth docs +description: Developer documentation for Modrinth! template: splash hero: - tagline: Congrats on setting up a new Starlight project! + tagline: Developer documentation for Modrinth actions: - - text: Example Guide - link: /guides/example/ + - text: API documentation + link: /api icon: right-arrow - - text: Read the Starlight docs - link: https://starlight.astro.build + - text: Get support with Modrinth + link: https://support.modrinth.com icon: external variant: minimal ---- - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -## Next steps - - - - Edit `src/content/docs/index.mdx` to see this page change. - - - Add Markdown or MDX files to `src/content/docs` to create new pages. - - - Edit your `sidebar` and other config in `astro.config.mjs`. - - - Learn more in [the Starlight Docs](https://starlight.astro.build/). - - +--- \ No newline at end of file diff --git a/apps/docs/src/content/docs/reference/example.md b/apps/docs/src/content/docs/reference/example.md deleted file mode 100644 index 0224f096c..000000000 --- a/apps/docs/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/apps/frontend/src/public/promo-frame-rev-iq.html b/apps/frontend/src/public/promo-frame-rev-iq.html index 75ad6c61f..dad1819e4 100644 --- a/apps/frontend/src/public/promo-frame-rev-iq.html +++ b/apps/frontend/src/public/promo-frame-rev-iq.html @@ -4,12 +4,7 @@ Modrinth App Ad - +