daenamnu/discordeno
1
0
Fork 0
mirror of https://github.com/discordeno/discordeno.git synced 2026-05-31 16:00:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update contributing docs (#3386)

Browse Source 
* Update docusaurus typescript setup for v3

And fix lint-staged and eslint

* Enable automatic JSX runtime

* Remove babel config and dependencies

* update yarn.lock

* add typecheck to site workflow

* update typedoc config

* downgrade docusaurus packages

* Update site.yml

* Type context and options in webpack-docusaurus-plugin.ts

* Update contributing docs

remove howToUseTurborepo.md
update devcontainer
update task to remove error matcher
remove useless packages/rest/src/README.md
remove readme.hbs

* Add notice for the clean build

---------

Co-authored-by: Matt Hatcher <3768988+MatthewSH@users.noreply.github.com>
This commit is contained in:
Fleny
2024-03-08 05:40:27 +01:00
committed by GitHub
parent 3d495dd3b5
commit edbb134efa
8 changed files with 150 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.devcontainer/base.Dockerfile
View File

@@ -1,17 +0,0 @@
# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 18, 16, 14, 18-bullseye, 16-bullseye, 14-bullseye, 18-buster, 16-buster, 14-buster
ARG VARIANT=18-bullseye
FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
# Install tslint, typescript. eslint is installed by javascript image
ARG NODE_MODULES="tslint-to-eslint-config typescript"
COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers
RUN su node -c "umask 0002 && npm install -g ${NODE_MODULES}" \
&& npm cache clean --force > /dev/null 2>&1
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment if you want to install an additional version of node using nvm
# ARG EXTRA_NODE_VERSION=10
# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"

2
.devcontainer/devcontainer.json
View File

@@ -17,7 +17,7 @@
// Configure properties specific to VS Code.
"vscode": {
// Add the IDs of extensions you want installed when the container is created.
"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "TabNine.tabnine-vscode"]
"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
}
},

3
.vscode/tasks.json vendored
View File

@@ -14,7 +14,8 @@
"runOptions": {
"runOn": "folderOpen",
"instanceLimit": 1
}
},
"problemMatcher": []
}
]
}

2
README.md
View File

@@ -128,6 +128,8 @@ You can run unit tests on all packages using
yarn test:unit
```
Other useful information are available on the [website under the contributing documentation](https://discordeno.js.org/docs/contributing)
Other useful scripts
(if you run in the package's directory, you need build dist before for test and types before for lint/fmt. Running in root directory should automatically do it for you)

76
howToUseTurborepo.md
View File

@@ -1,76 +0,0 @@
# Turborepo starter
This is an official Yarn v1 starter turborepo.
## What's inside?
This turborepo uses [Yarn](https://classic.yarnpkg.com/) as a package manager. It includes the following packages/apps:
### Apps and Packages
- `docs`: a [Next.js](https://nextjs.org/) app
- `web`: another [Next.js](https://nextjs.org/) app
- `ui`: a stub React component library shared by both `web` and `docs` applications
- `eslint-config-discordeno`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`)
- `tsconfig`: `tsconfig.json`s used throughout the monorepo
Each package/app is 100% [TypeScript](https://www.typescriptlang.org/).
### Utilities
This turborepo has some additional tools already setup for you:
- [TypeScript](https://www.typescriptlang.org/) for static type checking
- [ESLint](https://eslint.org/) for code linting
- [Prettier](https://prettier.io) for code formatting
### Build
To build all apps and packages, run the following command:
```
cd my-turborepo
yarn run build
```
### Develop
To develop all apps and packages, run the following command:
```
cd my-turborepo
yarn run dev
```
### Remote Caching
Turborepo can use a technique known as [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching) to
share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.
By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't
have an account you can [create one](https://vercel.com/signup), then enter the following commands:
```
cd my-turborepo
npx turbo login
```
This will authenticate the Turborepo CLI with your
[Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).
Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your turborepo:
```
npx turbo link
```
## Useful Links
Learn more about the power of Turborepo:
- [Pipelines](https://turbo.build/repo/docs/core-concepts/monorepos/running-tasks)
- [Caching](https://turbo.build/repo/docs/core-concepts/caching)
- [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching)
- [Filtering](https://turbo.build/repo/docs/core-concepts/monorepos/filtering)
- [Configuration Options](https://turbo.build/repo/docs/reference/configuration)
- [CLI Usage](https://turbo.build/repo/docs/reference/command-line-reference)

16
packages/rest/src/README.md
View File

@@ -1,16 +0,0 @@
# Discordeno Rest
A standalone and server-less REST module with functionality of REST, independently.
- Easily host on any serverless infrastructure.
- Easy to use and setup with Cloudflare Workers (FREE for 100K requests per day!)
- Freedom from global rate limit errors
- As your bot grows, you want to handle global rate limits better. Shards don't communicate fast enough to truly
handle it properly so this allows 1 rest handler across the entire bot.
- In fact, you can host multiple instances of your bot and all connect to the same rest server.
- REST does not rest!
- Separate rest means if your bot for whatever reason crashes, your requests that are queued will still keep going and
will not be lost.
- Seamless updates! When you want to update and reboot the bot, you could potentially lose tons of messages or
responses that are in queue. Using this you could restart your bot without ever worrying about losing any responses.
- Scalability! Scalability! Scalability!

4
readme.hbs
View File

@@ -1,4 +0,0 @@
---
sidebar_position: 1
---
{{>main}}

165
website/docs/contributing.md
View File

@@ -6,57 +6,182 @@ I can appreciate the struggle and obstacles that are in the way to contributing
## Finding Something To Contribute To
If you are in a position where you want to contribute but are not sure what you can contribute, look no further than the GitHub issues marked with the [**[HELP WANTED] good first issue**](https://github.com/discordeno/discordeno/issues?q=is%3Aopen+is%3Aissue+label%3A%22%5BHELP+WANTED%5D+good+first+issue%22) label. When an issue is marked with this label, it means that this is an easy issue to tackle and can be done by anyone.
If you are in a position where you want to contribute but are not sure what you can contribute, look no further than the GitHub issues marked with the [**good first issue**](https://github.com/discordeno/discordeno/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) label. When an issue is marked with this label, it means that this is an easy issue to tackle and can be done by anyone.
To view all the issues with this label:
To view all the issues with this label: https://github.com/discordeno/discordeno/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue
## Setting Up Coding Environment To Contribute
Alrighty then, by now you have something you want to contribute yourself or have found one of the issues you want to help close. Once your ready:
Alright then, by now you have something you want to contribute yourself or have found one of the issues you want to help close. Once your ready:
**One Time Steps:**
- Install Node.js
- Install [Node.js](https://nodejs.org/en) version 18+
- Install Yarn (`corepack enable`)
- [Fork the repo.](https://github.com/discordeno/discordeno/fork)
- Git clone the project.
- Make a copy of the `.env.example` file and call it `.env` file. Then put a test bot's token in there. For the Guild id, you should make a server and enable the Community setting and invite this test bot there.
- yarn
- yarn lint
- Git clone the project on your local machine
- Run `yarn` to install the dependencies
**For Every Contribution:**
- Make a new branch
- Make your code changes now.
- Make your code changes
- Perform testing
- Push to the repo and make a pull request
## Testing
For every contribution you make you can run the `Unit` and `E2E`tests to make sure all the code is still running correctly
- yarn test:unit
- yarn test:e2e
- Push to the repo and make a pull request.
- yarn test:e2e\*
\* You need to setup some environment variables to run this script, see below
## Understanding Yarn Scripts
### E2E environment requirement
### yarn fmt
The scripts `test:e2e` requires some additional setup. This is because it will run a complete test for the entire library connecting directly to discord to verify that the code is working correctly and can correctly handle discord messages / api requirements
This will format your code to match the rest of the codebase. This should be ran once you are ready to push and before making the pull request.
You can do this only once and don't need to do this every time:
### yarn lint
- Make a copy of the `.env.example` file and call it `.env` file.
- Fill the variables in the file
- Put a test bot's token in the `DISCORD_TOKEN` env.
- For the Guild id, you should make a server and enable the Community setting and invite this test bot there.
### Running test for Deno and Bun
Since discordeno supports Node.js but also Deno and Bun you can run tests for them too:
- Bun: `yarn test:bun-unit`
- Deno: `yarn test:deno-unit`
Keep in mind that running those will require you to have `Bun` and/or `Deno` installed based on what you run.
## Documentation / Website
If you want to contribute to the documentation you need some additional setup
- Run `yarn` to install the dependencies inside the root folder of the project
- Run `yarn release-build` to build the entire project
- Run `yarn build:doc` to generate the documentation from the comments in the code
- Run `yarn` inside the `website` folder to install the dependencies
Done this you are ready to start editing the code, you will find the documentation under the `website/docs` folder with `.md` and `.mdx`. We use `docusaurus` to manage the site and it does treat all `.md` and `.mdx` file like `.mdx` ones, so you will need to make sure you don't use invalid syntax, you can check out the [docusaurus documentation](https://docusaurus.io/docs/markdown-features/react) for more details.
In case you need to modify some React components you will find the code inside the `website/src` folder.
## Understanding Repo setup
### Yarn
As a package manager for the dependencies we use `yarn` on version 4 (`berry`). You can install it with the `corepack enable` command. Corepack is a feature that is built into node.js, however you might need to install it, in such cases you can run `npm install -g corepack`
### Turborepo
To manage the multiple packages we use a combination of yarn workspaces and turborepo. Turborepo is run by every script that you run from yarn in the root folder of the project, if you go inside a specific package, for example `packages/bot` it will run the local script and not turbo.
The workspaces are setup for all the folders inside `packages`. A few of the package are for the configuration of this repository, such as:
- `eslint-config-discordeno` - Configures eslint (with the prettier plugin) for the entire turborepo project
- `tsconfig` - Configures the base `tsconfig.json` for every package inside the turborepo project
Other node projects outside `packages` are not managed by turborepo and they require their own setup, an example is the website in `website/` that requires you to install its dependencies manually outside from the main dependencies that are used with the packages.
### lint-staged & Husky
The project is setup to have Husky to install after you run `yarn` in the root folder of the project and will setup 2 hooks:
- When you pull/merge: install the dependencies if they changed
- Before commit: Running lint-staged
lint-staged is configured in the `/package.json` file and will run
- Prettier for any changes you make to a source file, markdown file, html file or css file
- Eslint with the "normal" configuration resolved based on `eslint-config-discordeno` for every file (outside `website/`)
- Eslint with the configuration for the website for any source file you edit in the `website/` directory
There will run automatically when `git` performs one of those actions (merge/commit), this might however slow down commit time as it requires some time to run `list-staged`
### Yarn scripts
There a bunch of scripts but we will list the most important ones
#### `yarn build`
This will compile the TypeScript code into Javascript using SWC, it will not compile the type definitions (`.d.ts`) files.
:::note
This will clear the previus build file creating a clean build.
:::
#### `yarn build:type`
This will invoke the Typescript compiler (tsc) to compile the type definitions (`.d.ts`) files
#### `yarn release-build`
This will run both the `build` script and `build:type` one.
#### `yarn fmt`
This will format your code to match the rest of the codebase.
This will run every time you make a commit. If you disable this you should still run it manually before creating the pr
#### `yarn lint`
This will do all the checking and linting to make sure your code is in a useable state. There is also one other key thing to note about this. When you change something in the `@discordeno/types` package, you can run `yarn lint` to rebuild all the types.
### yarn test:unit
#### `yarn test:unit`
This will run all the unit tests to make sure anything you changed, did not break any unexpected things.
### yarn test:e2e
#### `yarn test:unit-coverage`
This will run all the end to end tests to make sure anything you changed, did not break any unexpected things. This takes much longer as these tests actually run across the network using the bot token you provided in the .env file. It makes many requests to test the entire library. This should not be spammed as your bot token has rate limits. Use once your code changes are finalized to make sure that everything is working properly before pushing.
This will run the unit tests and give you the coverage of them both in the console and in a `coverage` folder
#### `yarn test:deno-unit`
This will run all the unit tests like `yarn test:unit` but with Deno as the runtime instead of Node.js
:::note
This script requires Deno to be installed. See [deno install](https://docs.deno.com/runtime/manual) page for details
:::
#### `yarn test:bun-unit`
This will run all the unit tests like `yarn test:unit` and `yarn test:deno-unit` but with Bun as the runtime instead of Node.js or Deno
:::note
This script requires Bun to be installed. See [bun install](https://bun.sh/docs/installation) page for details
:::
#### `yarn test:integration`
This will run integration tests. Integration tests do not connect to discord and use fake data to verify that everything is working correctly.
#### `yarn test:test-type`
This will verify that the tests do not have type errors.
#### `yarn test:e2e`
This will run all the end to end tests to make sure anything you changed, did not break any unexpected things.
This takes much longer as these tests actually run across the network using the bot token you provided in the `.env` file. It makes many requests to test the entire library. This should not be spammed as your bot token has rate limits. Use once your code changes are finalized to make sure that everything is working properly before pushing.
:::note
This requires you have setup the required environment variables, see above for more details
:::
## Recommended code editor
- The recommended code editor is [Visual Studio code.](https://code.visualstudio.com)
## Notes
- If the contribution is relatively small go ahead and do it! If it is a larger change, I would highly recommend you read the guides we have on the website in order to understand our library better before undertaking such a big action.
- If an issue exists for the contribution you want to make, leave a comment on it so no one else begins working on it as well. If an issue does NOT exist for the contribution, then create an issue first before working on it to get some feedback to decide whether it is worth doing.
- Formatting and linting will be automatically handled by Husky and lint-staged. However, if it doesn't work you can format by doing `yarn fmt` and you can lint by doing `yarn lint`.
- Formatting and linting will be automatically handled by Husky and lint-staged. However, if it doesn't work you can format by doing `yarn fmt` and you can lint by doing `yarn lint`.
- If you want to edit a docker app (rest proxy for example), the website or some examples you will need to run `yarn` to install the dependencies of those