From 9677624951dcff3dea17e277015ca65dc7f2f02e Mon Sep 17 00:00:00 2001 From: Ayyan Date: Mon, 25 Jan 2021 17:24:52 +0400 Subject: [PATCH] docs(CONTRIBUTING): improve wording & add sections (#456) * docs: improve wording & add sections * idk * inclusive code * fmt --- .github/CONTRIBUTING.md | 98 ++++++++++++++++------------------------- README.md | 2 +- 2 files changed, 39 insertions(+), 61 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7bdba325d..124c70cdb 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,69 +1,47 @@ -# Fundamental Design Goals +# Contributing -This document serves to outline the overall design goals of the project. Please -see below a list of these fundamentals. +- Read the [style guide](#style-guide). +- Ask for help on the [official Discord server](https:) +- If you are going to work on an issue, mention so in the issue comments before + you start working on the issue. +- If you are going to work on a new feature, create an issue and discuss with + other contributors before you start working on the feature. +- Abide by and heed to + [Discord Developer Terms of Service](https://discord.com/developers/docs/legal) -## Do not allow anything Discord does not permit +## Submitting a Pull Request -Prevent any and all attempts of making user bots. If someone connects and the -client.user is not a bot user then throw an error immediately. +- Give the PR a descriptive title. -Do not support non-bot features like Group DMs or dm calls etc... +Examples of good PR title: -## Prettier Philosophy Regarding Options +- fix(controllers): cache member from INTERACTION_CREATE payload +- docs: improve wording +- feat(handlers): add editGuild() function Examples of bad PR title: +- fix #7123 +- update docs +- fix bugs -Avoid options/customizable whenever possible. Always enforce default values. -Except in cases like intents where the user should be able to pick which intents -to listen for. - -## Security - -Permission checks should be done by the library! We can throw a custom error -that shows which permissions are missing in order to run this request and save -an API call. This will also prevent bots from getting banned due to Missing -Access errors. - -Typescript 3.8 provides **TRUE** private props and methods that no one can -access. We will use this to our advantage to truly make a proper API. This isn't -a silly `_` to mark it as a private but the user should NEVER be able to access -it no matter what. - -## Functional API - -Events emitted by the client, for example the message creation event, should not -emit a `Message` class instance, but instead a _POJO_ (Plain Ol' JavaScript -Object). This will overall make a cleaner and more performant API, while -removing the headaches of extending built-in classes, and inheritance. - -Use functions when possible instead of an event emitter to prevent emitter -related memory leak issues or a number of other headaches that arise. - -TLDR: Avoid `classes` whenever possible. Avoid `loops` whenever possible(opt for -iterations like .forEach, map reduce, some find etc...) - -## Documentation - -Use `/** Description here */` comments above all properties and methods to -describe it so that VSC and other good IDE's with intellisense can pick it up -and provide the documentation right inside the IDE preventing a developer from -needing Discord API docs or even Deno documentation. - -We should have a step by step guide nonetheless but this is a POST v1 launch. We -should have a template repo to creating a boilerplate bot. - -## Backwards Compatibility BS - -Backwards compatibility is the death of code. It causes clutter and uglyness to -pile up and makes developers lazier. There will be no such thing as backwards -compatibility reasons in Discordeno. We will always support the latest and -greatest of JS. The end! Users can fork the lib at any commit to keep older -versions until they are ready to update. - -That said, we don't expect many things to be changing drastically after v1. As -you can imagine Typescript allows the latest and greatest of JS so we will be -ahead of the curve for years to come. +- Ensure there is a related issue and it is referenced in the pull request text. +- Ensure there are tests that cover the changes. +- Ensure all of the checks (lint and test) are passing. ## Style Guide -Prettier is our style guide. No discussions around styling ever. The options are -set and that is all. When you code let prettier handle the styling. PERIOD! +- Use underscores as a separator in filenames. +- Comply with + [these guidelines for inclusive code](https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md). +- An exported function must not have more than 4 individual parameters, the rest + arguments should be encorporated inside an object as a single parameter. +- Export all interfaces, types, and enums that are used for or inside an + exported entity. +- Every exported entity must be accompanied by a Typedoc (JSDoc without explicit + types) comment block. Ideally, we prefer single line comment block. +- Top-level functions should not use arrow syntax. +- Minimize dependencies; do not make circular imports. +- Utilize functional API wherever possible and avoid usage of ES6 classes. +- Follow + [Convention Over Configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) + wherever possible. +- Please follow the + [guidelines for inclusive code](https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md). diff --git a/README.md b/README.md index 9f39ecaa5..9b1464acd 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ forwarding a request to the API so that the client does not get globally-banned by Discord. - **Efficient & lightweight**: Discordeno is simplistic, easy-to-use, versatile, - and efficient. Uses + and efficient. Follows [Convention Over Configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) design paradigm ― prefers defaults that Discord recommends or the best configuration for the majority of the users.