Merge pull request #43 from discord-modmail/feat/extensions

feat: extension and plugin loading system

### Added

- Bot modes to determine behavior. Multiple can be applied at once.
  - PROD: the default mode, no dev extensions or dev plugins load
  - DEVELOP: the bot developer mode, most useful for people adding features to modmail
    - Enables the extension_manager extension.
  - PLUGIN_DEV: the plugin developer mode, useful for enabling plugin specific features
    - This is not used yet.
- Extension loading system
  - scans for extensions in the `modmail/extensions` folder and loads them if they are of the right format.
  - all extensions must be loadable as a module, which means they must have `__init__.py` files in their directories.
- Plugin loading system
  - scans for plugins in the `modmail/plugins` folder and loads them.
  - Unlike extensions, plugins and their respective folders do not need to have `__init__.py` files and are allowed to be symlinks.
- Extension management commands
  - load, reload, unload, list, refresh commands for dealing with extensions
  - Run the `ext` command for more details when bot is in `DEVELOP` mode.
- Plugin management commands
  - load, reload, unload, list, refresh commands for dealing with plugins
  - Run the `plugins` command for more details.
- Extension metadata
  - used to determine if a cog should load or not depending on the bot mode
- Plugin helper file
  - `modmail/plugin_helpers.py` contains several helpers for making plugins
    - `PluginCog`
    - `ModmailBot`, imported from `modmail.bot`
    - `ModmailLogger`, imported from `modmail.log`
- Meta Cog
  - NOTE: The commands in this cog are not stabilized yet and should not be relied upon.
  - Prefix command for getting the set prefix. Most useful by mentioning the bot.
  - Uptime command which tells the end user how long the bot has been online.
  - Ping command to see the bot latency.
- Guide on how to contribute to modmail, CONTRIBUTING.md
- Starts a Changelog

### Fixed

- Make the bot http_session within an event loop.

.codecov.yml

@@ -35,7 +35,8 @@ coverage:
         # advanced
         branches:
           - main
-        if_ci_failed: error #success, failure, error, ignore
+        if_ci_failed: ignore #success, failure, error, ignore
+        informational: true
         only_pulls: true
 
 

.env.template

@@ -0,0 +1 @@
+TOKEN="MyBotToken"

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,4 +7,5 @@ We highly recommend linking to an issue that has been approved by a maintainer,
 <!-- Link the issue by typing: "Closes #<number>" (Closes #0 to close issue 0 for example). -->
 
 ## Description
+
 <!-- Describe what changes you made, and how you've implemented them. -->

.github/workflows/changelog.yml

@@ -0,0 +1,22 @@
+# Github Action Workflow enforcing our changelog style of enforcing PR number.
+# credit: https://github.com/psf/black/blob/main/.github/workflows/changelog.yml
+
+name: Changelog Entry Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled, reopened]
+
+jobs:
+  build:
+    name: Changelog Entry Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Grep CHANGES.md for PR number
+        if: contains(github.event.pull_request.labels.*.name, 'skip changelog') != true
+        run: |
+          grep -Pz "\((\n\s*)?#${{ github.event.pull_request.number }}(\n\s*)?\)" CHANGELOG.md || \
+          (echo "Please add '(#${{ github.event.pull_request.number }})' change line to CHANGELOG.md" && \
+          exit 1)

.pre-commit-config.yaml

@@ -15,6 +15,16 @@ repos:
       - id: trailing-whitespace
         args: [--markdown-linebreak-ext=md]
 
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.8
+    hooks:
+      - id: mdformat
+        files: '\.md$'
+        exclude: 'tests/docs.md'
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat-black
+
   - repo: https://github.com/pre-commit/pygrep-hooks
     rev: v1.9.0
     hooks:

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2021-08-13
+
+### Added
+
+- Bot modes to determine behavior. Multiple can be applied at once. (#43)
+  - `PROD`: the default mode, no dev extensions or dev plugins load
+  - `DEVELOP`: the bot developer mode, most useful for people adding features to modmail
+    - Enables the extension_manager extension.
+  - `PLUGIN_DEV`: the plugin developer mode, useful for enabling plugin specific features
+    - This is not used yet.
+- Extension loading system (#43)
+  - scans for extensions in the `modmail/extensions` folder and loads them if they are of the right format.
+  - all extensions must be loadable as a module, which means they must have `__init__.py` files in their directories.
+- Plugin loading system (#43)
+  - scans for plugins in the `modmail/plugins` folder and loads them.
+  - Unlike extensions, plugins and their respective folders do not need to have `__init__.py` files and are allowed to be symlinks.
+- Extension management commands (#43)
+  - load, reload, unload, list, refresh commands for dealing with extensions
+  - Run the `ext` command for more details when bot is in `DEVELOP` mode.
+- Plugin management commands (#43)
+  - load, reload, unload, list, refresh commands for dealing with plugins
+  - Run the `plugins` command for more details.
+- Extension metadata (#43)
+  - used to determine if a cog should load or not depending on the bot mode
+- Plugin helper file (#43)
+  - `modmail/plugin_helpers.py` contains several helpers for making plugins
+    - `PluginCog`
+    - `ModmailBot`, imported from `modmail.bot`
+    - `ModmailLogger`, imported from `modmail.log`
+- Meta Cog (#43)
+  - **NOTE**: The commands in this cog are not stabilized yet and should not be relied upon.
+  - Prefix command for getting the set prefix. Most useful by mentioning the bot.
+  - Uptime command which tells the end user how long the bot has been online.
+  - Ping command to see the bot latency.
+- Guide on how to contribute to modmail, see [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Start a Changelog
+
+### Fixed
+
+- Make the bot http_session within an event loop.
+
+[0.1.0]: https://github.com/discord-modmail/modmail/releases/tag/v0.1.0
+[unreleased]: https://github.com/discord-modmail/modmail/compare/v0.1.0...main

CONTRIBUTING.md

@@ -0,0 +1,243 @@
+# Contributing Guidelines
+
+Thank you so much for your interest in contributing!. All types of contributions are encouraged and valued. See below for different ways to help, and details about how this project handles them!
+
+Please make sure to read the relevant section before making your contribution! It will make it a lot easier for us maintainers to make the most of it and smooth out the experience for all involved. 💚
+
+> **NOTE**: failing to comply with our guidelines may lead to a rejection of the contribution.
+> However, most features that are rejected can be written as a plugin, and used on your
+> modmail, without blocking you from getting updates.
+
+If you are confused by any of these rules, feel free to ask us in the `#support` channel in our  [Discord server.][modmail-discord]
+
+## How do I...
+
+- Ask or Say Something 🤔🐛😱
+  - [Request Support](#request-support)
+  - [Report an Error or Bug](#report-an-error-or-bug)
+  - [Request a Feature](#request-a-feature)
+- Make Something 🤓👩🏽‍💻📜🍳
+  - [Project Setup](#project-setup)
+  - [Contribute Code](#contribute-code)
+- Style Guides ✅🙆🏼💃👔
+  - [Git Commit Messages](#git-commit-messages)
+  - [Python Styleguide](#python-styleguide)
+  - [Changelog Requirement](#changelog-requirement)
+
+## Request Support
+
+- You can either ask your question as issue by opening one at [discord-modmail/modmail/issues][modmail-issues].
+
+- [Join the Modmail Discord Server][modmail-discord]
+
+  - Even though Discord is a chat service, sometimes it takes several hours for community members to respond — please be patient!
+  - Use the `#support` channel for questions or discussion about writing or contributing to Discord Modmail bot.
+  - There are many other channels available, check the channel list
+
+## Report an Error or Bug
+
+If you run into an error or bug with the project:
+
+> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
+
+- Open an Issue at [discord-modmail/modmail/issues][modmail-issues].
+- Explain the problem and include additional details to help maintainers reproduce the problem:
+  - **Use a clear and descriptive title** for the issue to identify the problem.
+  - **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, **don't just say what you did but explain how you did it**.
+  - **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/paste-able snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+  - **Describe the behaviour you observed after following the steps** and point out what exactly is the problem with that behaviour.
+  - **Explain which behaviour you expected to see instead and why.**
+  - **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. If you use the keyboard while following the steps, **record the GIF with the [Keybinding Resolver](https://github.com/atom/keybinding-resolver) shown**. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) on Linux (of course there are plenty more).
+
+## Request a Feature
+
+If the project doesn't do something you need or want it to do:
+
+- Open an Issue at [discord-modmail/modmail/issues][modmail-issues].
+- Provide as much context as you can about what you're running into.
+  - **Use a clear and descriptive title** for the issue to identify the suggestion.
+  - **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
+  - **Provide specific examples to demonstrate the steps**. Include copy/paste-able snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
+  - **Explain why this enhancement would be useful** to Modmail, and would benefit the community members.
+- Please try and be clear about why existing features and alternatives would not work for you.
+
+Once it's filed:
+
+- The Maintainers will [label the issue](#label-issues).
+- The Maintainers will evaluate the feature request, possibly asking you more questions to understand its purpose and any relevant requirements. If the issue is closed, the team will convey their reasoning and suggest an alternative path forward.
+- If the feature request is accepted, it will be marked for implementation with `status: approved`, which can then be done either by a core team member or by anyone in the community who wants to contribute code.
+
+> **Note**: The team is unlikely to be able to accept every single feature request that is filed. Please understand if they need to say no. However for most features requested, you can always write a plugin for your modmail bot.
+
+## Project Setup
+
+So you want to contribute some code! That's great! This project uses GitHub Pull Requests to manage contributions, so [read up on how to fork a GitHub project and file a PR](https://guides.github.com/activities/forking) if you've never done it before.
+
+### Test Server and Bot Account
+
+You will need your own test server and bot account on Discord to test your changes to the bot.
+
+1. Create a test server.
+1. Create a bot account and invite it to the server you just created.
+
+<!---
+TODO: Add required channel and role IDS when needed.
+-->
+
+Note down the IDs for your server.
+Learn how to obtain the ID of a server, channel or role **[here](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-).**
+
+### Fork the Project
+
+You will need your own remote (online) copy of the project repository, known as a fork.
+You will do all your work in the fork rather than directly in the main repository.
+
+You can click [here to fork][fork]
+
+And you should be ready to go!
+
+Once you have your fork you will need to clone the repo to your computer.
+
+```sh
+$ git clone https://github.com/<your username>/modmail
+...
+$ cd modmail
+```
+
+or using the [github cli](https://github.com/cli/cli):
+
+```sh
+$ gh repo clone <your username>/modmail
+...
+$ cd modmail
+```
+
+> Tip: You can use the github cli to fork the repo as well, just use `gh repo fork discord-modmail/modmail` and it will allow you to clone it directly.
+
+### Install development dependencies
+
+Make sure you are in the project directory.
+
+```sh
+# This will install the development and project dependencies.
+poetry install
+# This will install the pre-commit hooks.
+poetry run task precommit
+```
+
+### Set up environment variables
+
+1. Create a text file named `.env` in your project root (that's the base folder of your repository):
+   - You can also copy the `.env.template` file to `.env`
+
+> Note: The entire file name is literally `.env`
+
+1. Open the file with any text editor.
+1. Each environment variable is on its own line, with the variable and the value separated by a `=` sign.
+
+#### The following variables are needed for running Modmail:
+
+| Required | ENV VARIABLE NAME | TYPE    | WHAT IS IT?                                      |
+| -------- | ----------------- | ------- | ------------------------------------------------ |
+| True     | `TOKEN`           | String  | Bot Token from the Discord developer portal      |
+| False    | `DEVELOP`         | Boolean | Enables the developer bot extensions             |
+| False    | `PLUGIN_DEV`      | Boolean | Enables plugin-developer friendly bot extensions |
+
+The rest of them can be viewed in our [.env.template](./.env.template)
+
+### Run The Project
+
+To run the project, use the (below) in the project root.
+
+```shell
+$ poetry run task start
+```
+
+## Contribute Code
+
+We like code commits a lot! They're super handy, and they keep the project going and doing the work it needs to do to be useful to others.
+
+Code contributions of just about any size are acceptable!
+
+To contribute code:
+
+- [Set up the project](#project-setup).
+- Make any necessary changes to the source code.
+- Write clear, concise commit message(s).
+  - A more in-depth guide to writing great commit messages can be found in Chris Beam's [*How to Write a Git Commit Message*](https://chris.beams.io/posts/git-commit/).
+- Run `flake8`, `black` and `pre-commit` against your code **before** you push. Your commit will be rejected by the build server if it fails to lint. You can run the lint by executing `poetry run task lint` in your command line.
+- Go to [discord-modmail/modmail/pulls][modmail-pulls] and open a new pull request with your changes.
+- If PRing from your own fork, **ensure that "Allow edits from maintainers" is checked**. This permits maintainers to commit changes directly to your fork, speeding up the review process.
+- If your PR is connected to an open issue, add a line in your PR's description that says `Closes #123`, where `#123` is the number of the issue you're fixing. This will make github link your issue, and make it easier for us (and other contributers) to find and understand the context behind your PR.
+
+> Pull requests (or PRs for short) are the primary mechanism we use to change modmail. GitHub itself has some [great documentation][about-pull-requests] on using the Pull Request feature. We use the "fork and pull" model [described here][development-models], where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository.
+
+Once you've filed the PR:
+
+- Barring special circumstances, maintainers will not review PRs until lint checks pass (`poetry run task lint`).
+- One or more contributors will use GitHub's review feature to review your PR.
+- If the maintainer asks for any changes, edit your changes, push, and ask for another review.
+- If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly. 💚
+- If your PR gets accepted, it will be marked as such, and merged into the `main` branch soon after.
+
+## Git Commit Messages
+
+Commit messages must start with a short summary (max. 50 chars)
+written in the imperative, followed by an optional, more detailed explanatory
+text which is separated from the summary by an empty line.
+
+Commit messages should follow best practices, including explaining the context
+of the problem and how it was solved, including caveats or follow up changes
+required. They should tell the story of the change and provide readers
+understanding of what led to it.
+
+Check out [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for more information.
+
+If you're lost about what this even means, please see [How to Write a Git
+Commit Message](http://chris.beams.io/posts/git-commit/) for a start.
+
+In practice, the best approach to maintaining a nice commit message is to
+leverage a `git add -p` and `git commit --amend` to formulate a solid
+changeset. This allows one to piece together a change, as information becomes
+available.
+
+If you squash a series of commits, don't just submit that. Re-write the commit
+message, as if the series of commits was a single stroke of brilliance.
+
+That said, there is no requirement to have a single commit for a PR, as long as
+each commit tells the story. For example, if there is a feature that requires a
+package, it might make sense to have the package in a separate commit then have
+a subsequent commit that uses it.
+
+Remember, you're telling part of the story with the commit message. Don't make
+your chapter weird.
+
+## Python Styleguide
+
+<!-- TODO: ... -->
+
+## Changelog Requirement
+
+Modmail has CI that will check for an entry corresponding to your PR in `CHANGES.md`.
+If you feel this PR does not require a changelog entry please state that in a comment
+and a maintainer can add a `skip changelog` label to make the CI pass. Otherwise,
+please ensure you have a line in the following format:
+
+```
+- `Modmail` is now more awesome (#X)
+```
+
+Note that X should be your PR number, not issue number! This is not perfect but
+saves a lot of release overhead as now the releaser does not need to go back and
+workout what to add to the `CHANGES.md` for each release.
+
+## Attribution
+
+This contributing guide is inspired by the [Moby's](https://github.com/moby/moby) and [Atom Text Editor's](https://github.com/atom/atom) contributing guide.
+
+[about-pull-requests]: https://help.github.com/articles/about-pull-requests/
+[development-models]: https://help.github.com/articles/about-collaborative-development-models/
+[fork]: https://github.com/discord-modmail/modmail/fork
+[modmail-discord]: https://discord.gg/ERteGkedDW
+[modmail-issues]: https://github.com/discord-modmail/modmail/issues
+[modmail-pulls]: https://github.com/discord-modmail/modmail/pulls

Procfile

@@ -1 +1 @@
-worker: python -m modmail
+web: python -m modmail

README.md

@@ -1,8 +1,9 @@
 # modmail
+
 [![Lint & Test](https://img.shields.io/github/workflow/status/discord-modmail/modmail/Lint%20&%20Test/main?label=Lint+%26+Test&logo=github&style=flat)](https://github.com/discord-modmail/modmail/actions/workflows/lint_test.yml "Lint and Test")
 [![Code Coverage](https://img.shields.io/codecov/c/gh/discord-modmail/modmail/main?logo=codecov&style=flat&label=Code+Coverage)](https://app.codecov.io/gh/discord-modmail/modmail "Code Coverage")
 [![Codacy Grade](https://img.shields.io/codacy/grade/78be21a49835484595aea556d5920638?logo=codacy&style=flat&label=Code+Quality)](https://www.codacy.com/gh/discord-modmail/modmail/dashboard "Codacy Grade")
-[![Python](https://img.shields.io/static/v1?label=Python&message=3.8+|+3.9&color=blue&logo=Python&style=flat)](https://www.python.org/downloads/ "Python 3.8 | 3.9")
+[![Python](https://img.shields.io/static/v1?label=Python&message=3.8+%7C+3.9&color=blue&logo=Python&style=flat)](https://www.python.org/downloads/ "Python 3.8 | 3.9")
 [![License](https://img.shields.io/github/license/discord-modmail/modmail?style=flat&label=License)](./LICENSE "License file")
 [![Code Style](https://img.shields.io/static/v1?label=Code%20Style&message=black&color=000000&style=flat)](https://github.com/psf/black "The uncompromising python formatter")
 

SECURITY.md

@@ -8,7 +8,7 @@ versions long, as that may make contributing difficult.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| <  1.0  | :white_check_mark: |
+| \<  1.0 | :white_check_mark: |
 | >= 1.0  | Unreleased         |
 
 ## Reporting a Vulnerability