diff --git a/database-seeds/scripts/package.json b/database-seeds/scripts/package.json index bd8645634..cf0f015dc 100644 --- a/database-seeds/scripts/package.json +++ b/database-seeds/scripts/package.json @@ -4,7 +4,8 @@ "description": "Scripts for dealing with tachi-database-seeds.", "main": "", "scripts": { - "test": "./run-tests.sh" + "test": "./run-tests.sh", + "sort": "node deterministic-collection-sort.js" }, "author": "zkldi", "license": "MIT", diff --git a/docs/docs/contributing/components/documentation.md b/docs/docs/contributing/components/documentation.md index 8822d9e42..df22a43fb 100644 --- a/docs/docs/contributing/components/documentation.md +++ b/docs/docs/contributing/components/documentation.md @@ -11,6 +11,17 @@ To properly contribute to the documentation, you'll need to know the following t If you don't know, or aren't comfortable with all of the things on this list, click on them to learn about them! +## Component Overview + +All of the content for this component is inside the `docs/` folder. + +It contains another folder, inconveniently called `docs/`, which contains all of the markdown files that are our documentation. + +There's another folder called `includes/`, which contains some things that are constantly +referenced throughout the documentation. + +At the top level, there's `mkdocs.yml`, which we'll go over later. + ## Software Overview We use [MKDocs Material](https://squidfunk.github.io/mkdocs-material/) for our documentation. diff --git a/docs/docs/contributing/components/seeds.md b/docs/docs/contributing/components/seeds.md new file mode 100644 index 000000000..ac4bcc6b2 --- /dev/null +++ b/docs/docs/contributing/components/seeds.md @@ -0,0 +1,145 @@ +# Database Seeds Guide + +The database seeds component of Tachi controls the actual data inside the app. + +Changes made in this component are automatically synchronised with the live Tachi database, +it's kind of a cool system, and allows anyone to contribute patches to songs, charts, folders, and more! + +## Tool Knowledge + +To properly contribute to the documentation, you'll need to know the following things: + +- [The Terminal](../tools/terminal.md) +- [Git](../tools/git.md) +- [JSON](../tools/json.md) + +If you know JavaScript, that will be helpful for the scripting sections when we go over how +to batch-apply updates. +However, we don't maintain a JS guide (yet). You'll have to ask in `#dev`! + +If you don't know, or aren't comfortable with all of the things on this list, click on them to learn about them! + +## Component Overview + +All of the content for this component is inside the `database-seeds/` folder. + +It contains the `collections/` folder, which contains JSON files for their respective databases. + +!!! example + `collections/songs-iidx.json` will be synced with the `songs-iidx` collection in the database. + +The other available folder is `scripts/`. +This contains a Typescript package for scripting changes to the database seeds, and also contains a script that tests whether the data in the seeds is valid. +We'll go over this more later. + +## Software Overview + +The collections are all just plain JSON files. + +The scripts are written in either TypeScript or JavaScript. + +## Dependencies + +Installation of dependencies for this part of the codebase should be already handled, if you ran the `bootstrap.sh` script. + +## How do I know what a song is meant to look like? + +These are called schemas (or interfaces) and you can find them in two places: + +- The source code. + +You can find the actual interfaces we use inside the common module, it's at `common/src/types.ts`. This contains interface definitions like `SongDocument` which, +expectedly, define what a song is meant to look like. + +- The documentation. + +We also maintain a bit more human readable form for schemas in this documentation, under the [schemas section](../../schemas). + +!!! warning + This may be slightly out of sync with the current content. Please report it if it is! + +## Important Scripts + +After doing **anything** to the collections, such as adding a new item to the database, you **MUST** run `pnpm sort` inside the `scripts/` folder. + +This will deterministically sort the data you put into the collections, making sure that `git` history stays sane (i.e. it only says things that actually changed, changed). + +!!! info + `pnpm sort` is an alias for `node deterministic-collection-sort.js` + +Before sending any changes, run `pnpm test` to check all your data. If anything you've sent is invalid, it'll be logged in `failed-tests.log`, and the command won't pass. + +This is automatically ran when changes are sent to me, but you should run it yourself before committing anyway! + +!!! info + Your changes won't be synced with the database if they fail the tests. + + If you're confused about why tests are failing, ask in `#dev`. + +## Rerunners + +Inside the `scripts/` folder is a folder called `rerunners/`. +These scripts are intended to be kept around and re-ran (hence the name). + +You'll find a bunch of useful little utilities here, and there's sadly too many to document. + +It should be obvious what each one does, though. + +If you're looking to add a BMS table to Tachi for an example, you'd look into the rerunner scripts. + +## Single-Time Scripts + +Some scripts we only want to run once, and we don't really need to keep them around. These are saved into the `single-time` folder, and will never be tracked by `git`. + +You can make quick hacky scripts here. + +## Scripting Changes + +We provide utilities for mutating data inside the collections comfortably inside `scripts/util.js`. The most important one is `MutateCollection`, which, as expected, mutates a collection. + +It takes a collection name (like `songs-iidx.json`) and a callback function that receives the data inside that collection. + +Whatever that callback returns replaces the data in the collection. + +Below are some examples of what you can do with this API. + +=== "Batch Renaming an artist" + ```js + const { MutateCollection } = require("../util"); + + // Let's say all songs made by the artist "Scrimbly" were renamed to + // BEMANI SOUND TEAM "Scrimbly". + MutateCollection("songs-iidx.json", (songs) => { + // for all the songs in songs-iidx.json + for (const song of songs) { + // if the song artist is "Scrimbly" + if (song.artist === "Scrimbly") { + // replace it + song.artist = 'BEMANI SOUND TEAM "Scrimbly"' + } + } + + // return the same piece of data we got, with our mutations applied. + return songs; + }); + ``` + +=== "Adding data" + ```js + const { MutateCollection } = require("../util"); + + MutateCollection("songs-iidx.json", (songs) => { + songs.push({ + // some new song object + }) + + songs.push({ + // another new song object + }) + + // return the same piece of data we got, with our mutations applied. + return songs; + }); + ``` + +For even more examples, see the `rerunners/` folder, as it makes liberal use of this API. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 28e710400..6d30b3dc9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -32,6 +32,7 @@ nav: - Component-Specific Guides: - "contributing/components/issues.md" - "contributing/components/documentation.md" + - "contributing/components/seeds.md" - Tooling Guides: - "contributing/tools/terminal.md"