From a75387147a92f04c666237691783171c10245bee Mon Sep 17 00:00:00 2001 From: Neko Ayaka Date: Mon, 24 Feb 2025 11:31:00 +0800 Subject: [PATCH] docs(CONTRIBUTING.md): added --- .github/CONTRIBUTING.md | 342 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 342 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..00d1c2f28 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,342 @@ +# Start contributing to [airi](https://github.com/moeru-ai/airi) + +Hello! Thank you for your interest in contributing to this project. This guide will help you get started. + +## Prerequisites + +- [Git](https://git-scm.com/downloads) +- [Node.js 23+](https://nodejs.org/en/download/) +- [corepack](https://github.com/nodejs/corepack) +- [pnpm](https://pnpm.io/installation) + +
+Windows setup + +1. Open PowerShell +2. Install [`scoop`](https://scoop.sh/) + + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression + ``` + +3. Install `git`, `node` through `scoop` + + ```powershell + scoop install git nodejs + ``` + +4. Install `pnpm` through `corepack` + + ```powershell + corepack enable + corepack prepare pnpm@latest --activate + ``` + +
+ +
+macOS setup + +0. Open Terminal, (or iTerm2, Ghostty, Kitty, etc.) +1. Install `git`, `node` through `brew` + + ```shell + brew install git node + ``` + +2. Install `pnpm` through `corepack` + + ```shell + corepack enable + corepack prepare pnpm@latest --activate + ``` + +
+ +
+Linux setup + +0. Open Terminal +1. Follow [nodesource/distributions: NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions?tab=readme-ov-file#table-of-contents) to install `node` +2. Follow [Git](https://git-scm.com/downloads/linux) to install `git` +3. Install `pnpm` through `corepack` + + ```shell + corepack enable + corepack prepare pnpm@latest --activate + ``` + +
+ +## If you have already contributed to this project before + +> [!WARNING] +> +> If you haven't clone this repository, skip this section. + +Make sure your local repository is up to date with the upstream repository: + +```shell +git fetch -all +git checkout main +git pull upstream main --rebase +``` + +If you have a working branch, to make your branch up to date with the upstream repository: + +```shell +git checkout +git rebase main +``` + +## Fork this project + +Click on the **Fork** button on the top right corner of the [moeru-ai/airi](https://github.com/moeru-ai/airi) page. + +## Clone + +```shell +git clone https://github.com//airi.git +cd airi +``` + +## Create your working branch + +```shell +git checkout -b +``` + +## Install dependencies + +```shell +corepack enable +pnpm install +``` + +> [!NOTE] +> +> We would recommend to install [@antfu/ni](https://github.com/antfu-collective/ni) to make your script simpler. +> +> ```shell +> corepack enable +> npm i -g @antfu/ni +> ``` +> +> Once installed, you can +> +> - use `ni` for `pnpm install`, `npm install` and `yarn install`. +> - use `nr` for `pnpm run`, `npm run` and `yarn run`. +> +> You don't need to care about the package manager, `ni` will help you choose the right one. + +## Choose the application you want to develop on + +### Documentation site + +```shell +pnpm -F @proj-airi/docs... dev +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/docs... dev +> ``` + +### Stage web (Frontend for [airi.moeru.ai](https://airi.moeru.ai), or [airi.ayaka.io](https://airi.ayaka.io)) + +```shell +pnpm -F @proj-airi/stage-web... dev +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/stage-web... dev +> ``` + +### Stage Tamagotchi (Electron app for アイリ VTuber) + +```shell +pnpm -F @proj-airi/stage-tamagotchi... dev +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/stage-tamagotchi... dev +> ``` + +### Telegram bot integration + +A Postgres database is required. + +```shell +cd services/telegram-bot +docker compose up -d +``` + +Configure `.env` + +```shell +cp .env .env.local +``` + +Edit the credentials in `.env.local`. + +Migrate the database + +```shell +pnpm -F @proj-airi/telegram-bot db:generate +pnpm -F @proj-airi/telegram-bot db:push +``` + +Generate bundles for Monorepo packages + +```shell +pnpm packages:stub +``` + +Run the bot + +```shell +pnpm -F @proj-airi/telegram-bot start +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/telegram-bot... dev +> ``` + +### Discord bot integration + +```shell +cd services/discord-bot +``` + +Configure `.env` + +```shell +cp .env .env.local +``` + +Edit the credentials in `.env.local`. + +Generate bundles for Monorepo packages + +```shell +pnpm packages:stub +``` + +Run the bot + +```shell +pnpm -F @proj-airi/discord-bot start +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/discord-bot dev +> ``` + +### Minecraft agent + +```shell +cd services/minecraft +``` + +Start a Minecraft client, export your world with desired port, and fill-in the port number in `.env.local`. + +Configure `.env` + +```shell +cp .env .env.local +``` + +Edit the credentials in `.env.local`. + +Generate bundles for Monorepo packages + +```shell +pnpm packages:stub +``` + +Run the bot + +```shell +pnpm -F @proj-airi/minecraft-bot start +``` + +> [!NOTE] +> +> For [@antfu/ni](https://github.com/antfu-collective/ni) users, you can +> +> ```shell +> nr -F @proj-airi/minecraft-bot dev +> ``` + +## Commit + +### Before commit + +> [!CAUTION] +> +> Please make sure lint (static checkers) and TypeScript compilers are satisfied: +> +> ```shell +> pnpm packages:stub && pnpm lint && pnpm typecheck +> ``` + +> [!NOTE] +> +> If you have [@antfu/ni](https://github.com/antfu-collective/ni) installed, you can use `nr` to run the commands: +> +> ```shell +> nr packages:stub && nr lint && nr typecheck +> ``` + +### Commit + +```shell +git add . +git commit -m "" +``` + +### Push to your fork repository + +```shell +git push origin -u +``` + +You should be able to browse the branch on your fork repository. + +> [!NOTE] +> +> If this is your first time contributing with this project, you need to add the upstream repository too: +> +> ```shell +> git remote add upstream https://github.com/moeru-ai/airi.git +> ``` + +## Creating Pull Request + +Navigate to [moeru-ai/airi](https://github.com/moeru-ai/airi) page, click on the **Pull requests** tab, and click on the **New pull request** button, click on the **Compare across forks** link, and select your fork repository. + +Review the changes, and click on the **Create pull request** button. + +## Whooo-ya! You made it! + +Congratulations! You made your first contribution to this project. You can now wait for the maintainers to review your pull request.