130 lines
3.3 KiB
Markdown
130 lines
3.3 KiB
Markdown
# Contribution guide
|
|
|
|
## Table of contents
|
|
|
|
- [Contribution guide](#contribution-guide)
|
|
- [Table of contents](#table-of-contents)
|
|
- [Purpose](#purpose)
|
|
- [Assumptions](#assumptions)
|
|
- [Getting started](#getting-started)
|
|
- [Development environment](#development-environment)
|
|
- [Required knowledge](#required-knowledge)
|
|
- [Bot](#bot)
|
|
- [Web Interface](#web-interface)
|
|
- [Documentation](#documentation)
|
|
- [Commit message](#commit-message)
|
|
- [Creating / updating a command](#creating--updating-a-command)
|
|
- [Help message](#help-message)
|
|
- [Structure](#structure)
|
|
|
|
## Purpose
|
|
|
|
There are several goals this guide aims to achieve:
|
|
|
|
- Help new contributors get started
|
|
- Prevent information fragmentation as people work on different parts of the software
|
|
- Streamline the development workflow
|
|
- Make things work in the project owner's absence
|
|
- Minimize intervention and back-and-forth communication (e.g. The contributor didn't format their code properly)
|
|
|
|
## Assumptions
|
|
|
|
All contributors are assumed to be familiar with the following:
|
|
|
|
- git (and by extension github and developer collaboration)
|
|
- node.js and its ecosystem (npm packages, yarn, etc.)
|
|
- javascript and typescript
|
|
- code formatting
|
|
|
|
## Getting started
|
|
|
|
### Development environment
|
|
|
|
Contributors are free to use whatever IDE they want but the usage of [vscode](https://code.visualstudio.com) is highly recommended.
|
|
|
|
Format markdown file(s) with [prettier](https://prettier.io) formatter
|
|
|
|
### Required knowledge
|
|
|
|
### Bot
|
|
|
|
- [discord.js](https://discord.js.org)
|
|
- [sapphire framework](https://www.sapphirejs.dev)
|
|
|
|
### Web Interface
|
|
|
|
- [express.js](https://expressjs.com)
|
|
- [passport.js](https://www.passportjs.org)
|
|
- [firebase functions](https://firebase.google.com/docs/functions)
|
|
|
|
### Documentation
|
|
|
|
- [Docusaurus](https://docusaurus.io)
|
|
- [Markdown](https://www.markdownguide.org/basic-syntax)
|
|
|
|
## Commit message
|
|
|
|
The commit message should be a clear and concise description of what the commit does.
|
|
The first line should be no more than 50 characters and the rest no more than 72.
|
|
|
|
## Creating / updating a command
|
|
|
|
Use the `CustomCommand` defined in [src/custom/CustomCommand.ts](./src/custom/CustomCommand.ts) instead of importing from `@sapphire/framework`.
|
|
|
|
### Help message
|
|
|
|
- consistent usage information
|
|
|
|
### Structure
|
|
|
|
- one export per command
|
|
- functions should be `static` whenever possible
|
|
- Keep the `messageRun` function clean (ideally less than 50 lines).
|
|
- Separate regular imports from type imports.
|
|
- Separate the embedded message building process to a separate function.
|
|
|
|
This also makes testing easier
|
|
|
|
- jsdoc comments should...
|
|
|
|
- not include argument and return types.
|
|
|
|
They should be included in the function instead.
|
|
|
|
- not include a dash (`-`) in the `@returns` tag.
|
|
|
|
Do this:
|
|
|
|
```ts
|
|
/**
|
|
* This function does something.
|
|
*
|
|
* - Here's some extra information
|
|
*
|
|
* @param argument - This is an argument.
|
|
* @returns some string.
|
|
*/
|
|
function someFunction(argument: string): string {
|
|
const someString = "some string"
|
|
|
|
return someString
|
|
}
|
|
```
|
|
|
|
Not this:
|
|
|
|
```ts
|
|
/**
|
|
* This function does something.
|
|
*
|
|
* - Here's some extra information
|
|
*
|
|
* @param {string} argument - This is an argument.
|
|
* @returns {string} - some string.
|
|
*/
|
|
function someFunction(argument) {
|
|
const someString = "some string"
|
|
|
|
return someString
|
|
}
|
|
```
|