Skip to content

Latest commit

 

History

History
154 lines (111 loc) · 8.1 KB

CONTRIBUTING.md

File metadata and controls

154 lines (111 loc) · 8.1 KB

// based off FlyByWire Simulations Discord Bot - https://github.com/flybywiresim/discord-bot

Contributing

Please reference the information below when contributing to this repository.

Requirements

  • Write your commands professionally and clearly.
  • Proofread your work before submitting as ready for review.
  • Choose user-friendly command names.
  • Test your build locally before submitting as ready for review.

Writing Guidelines

To ensure that commands are written professionally and clearly, please follow the guide below.

  • Use the proper name for third party services. For example, simBrief and not SimBrief.
  • Refrain from using exclamation points unless it is a warning.
  • Ensure that the contents of the command are correct. If you are unsure if something is correct please speak to any bot developer, and they will be able to verify anything.
  • Ensure that grammar and spelling is correct.

Pull Request Process

Reminder: The main branch is 'staging'

  1. Fork the repo
  2. Clone to your local system using your IDE of choice
  3. Make a new branch from staging and name appropriately (e.g. feat: added IRS command, fix: typos fixed in IRS)
  4. Create/edit the command you are working on
  5. Test your build locally (Instructions below)
  6. Create a PR to merge your changes into staging

Note: It may be beneficial to create a draft PR while working on your command. This will allow us to see who is working on what, and will enable the community to give active feedback on your work.

Pull Request Template

You can find the pull request template here.

Testing Your Build

node and npm Install

  1. Install node, npm is bundled with the download
  2. Open a command prompt in your repo directory and run 'npm install'.

Bot Application

  1. Log into the Discord website and navigate to the applications page
  2. Click New Application
  3. Give your application a name
  4. Navigate to the Bot tab and click Add Bot. You will have to confirm by clicking Yes, do it!
  5. Click the Copy button underneath token. (Do not share this)
  6. Create a file called .env in your bot repo
  7. Inside the .env file, type DISCORD_TOKEN=TOKEN replacing TOKEN with what you copied in step 6
  8. You may need to add the .env file to your gitignore if your IDE hasn't done it automatically.

Some commands may require additional tokens. If you would like to test them out on your bot, you must include the tokens inside your .env file. These commands include the metar and station commands. Both of these use the same API meaning you only need one token. The steps below will explain how to set this up.

  1. Make a free account here. Then, follow the steps here to get your token
  2. Inside the .env file, on a new line type METAR_TOKEN=TOKEN replacing TOKEN with what you copied in step 1
  3. Then, on another new line within the .env file, type STATION_TOKEN=TOKEN replacing TOKEN with what you copied in step 1

Privileged Gateway Intents

Privileged Gateway Intents must now be enabled within the Discord Developer Portal in order for your bot to function. The steps below will explain how to enable them.

  1. Log into the Discord website and navigate to the applications page and select your application. Then select Bot under Settings
  2. Scroll down to the Privileged Gateway Intents section and enable all the intents.

Inviting the Bot to Your Server

  1. Create a Discord server where you can test your bot
  2. On the applications page, select your application and navigate to the OAuth2 tab. Then select bot under the scopes section
  3. Tick Administrator under the Bot Permissions section
  4. Click the Copy button and paste it into your browser of choice, invite it to your test server.

Running the Bot

  1. Open a command prompt in your repo directory
  2. Run npm run dev
  3. If all has gone well, you will see the bot is running as http://localhost:3000 and logged into the name of the bot you created!
  4. You can now test your commands

Ban Appeal Form

A ban appeal form is sent to a user when they are banned. The URL for the form is stored as an environment variable, BAN_APPEAL_URL. For testing, you could set to a URL like https://hdsimulations.com

MongoDB

Some commands require access to a MongoDB server to store persistence data. The steps below outline MongoDB's setup procedure, and the necessary steps to connect your application to your MongoDB instance.

  1. Install MongoDB from their website or set up an Atlas cluster
  2. If running MongoDB locally, run it as a service or from the terminal
  3. Create a new database named hd in your MongoDB instance
  4. Inside the .env file, on a new line type MONGODB_URL=URL replacing URL with your MongoDB access URL

If you have installed MongoDB locally, your access url will be mongodb://localhost:27017/hd. If you are using Atlas, the connection URL can be found under Connect->Connect your application in Database, located under Deployments.

Editing Methods

Adding a New Command

Please note, this will only show the basics of adding a command

  1. Create a new file in the relevant folder within src/commands/ and name it appropriately. yourcommand.ts
  2. Create your command
  3. Add it to src/commands/index.ts. You need to add the line import { name } from './commandfolder/filename';, replacing name with the export const from your command, commandfolder with the relevant folder your command has been placed within, and filename with the file name you created in step 1. (Add this below the last command.)
  4. Add your command name to the list under const commands: CommandDefinition[] = [
  5. Add your command name the COMMANDS.md index under the appropriate section in the .github directory
  6. Add your command to the CHANGELOG.md in the .github directory.

If you need help creating a command, you may find it useful to copy an existing command as a template, changing what you need.

Please ensure that the command category is appropriate for the command. You can find what each category means in src/lib/constants.ts. For example, a command used for support would use the 'SUPPORT' category.

Modifying a Command

All you need to do is open the command you wish to edit in src/commands/, edit what you need, commit and push!

Example Command

import { CommandDefinition } from '../../lib/command';
import { makeEmbed, makeLines } from '../../lib/embed';
import { CommandCategory } from '../../constants';

const IRS_IMAGE_URL = 'https://media.discordapp.net/attachments/984255062010396702/990392133825490994/IRS_Switch_POS.png'; //TODO: Add a more professional looking photo (square view of overhead panel), clean red box

export const irs: CommandDefinition = {
    name: 'irs',
    description: 'Display help with IRS alignment',
    category: CommandCategory.B78XH,
    executor: (msg) => {
        const irsEmbed = makeEmbed({
            title: 'Heavy Division | IRS',
            description: makeLines([
            'On the overhead panel you will see the two knobs labelled \'IRS\' left and right. Turn these two to the \'ON\' position. ',
            '',
            'You can check how long you have to wait by looking at the align time on the upper MFD. ',
            '',
            ' **It takes several minutes for the IRS to align.**',
            '',
            'To align the IRS instantly (not realistic) in the CDU select: ',
            '\'HEAVY\' -> \'IRS CONFIGURATION\' -> \'FORCE ALIGN\' ',
            ]),
            image: { url: IRS_IMAGE_URL },
            });

return msg.channel.send({ embeds: [irsEmbed] });
},
};