From ef101ccb9af91ad0b291d3e842925ce7754fc458 Mon Sep 17 00:00:00 2001 From: Michael H Date: Mon, 17 Feb 2020 22:42:13 -0500 Subject: [PATCH] [Docs] Cog Creator Guidelines (#3568) * Cog Creator Guidelines * print * docs warnings * Apply suggestions from code review Co-Authored-By: Flame442 <34169552+Flame442@users.noreply.github.com> * more feedback handling * one more Co-authored-by: Flame442 <34169552+Flame442@users.noreply.github.com> --- docs/guide_cog_creation.rst | 67 +++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst index 6ea670829..5786ec9f9 100644 --- a/docs/guide_cog_creation.rst +++ b/docs/guide_cog_creation.rst @@ -162,3 +162,70 @@ Additional resources Be sure to check out the :doc:`/guide_migration` for some resources on developing cogs for V3. This will also cover differences between V2 and V3 for those who developed cogs for V2. + + +--------------------------- +Guidelines for Cog Creators +--------------------------- + +The following are a list of guidelines Cog Creators should strive to follow. +Not all of these are strict requirements (some are) but are all generally advisable. + +1. Cogs should follow a few naming conventions for consistency. + + - Cog classes should be TitleCased, using alphabetic characters only. + - Commands should be lower case, using alphanumeric characters only. + - Cog modules should be lower case, using alphabetic characters only. + +2. Cogs and commands should have docstrings suitable for use in help output. + + - This one is slightly flexible if using other methods of setting help. + +3. Don't prevent normal operation of the bot without the user opting into this. + + - This includes as a side effect by blocking the event loop. + +4. If your cog uses logging: + + - The namespace for logging should be: ``red.your_repo_name.cog_name``. + - Print statements are not a substitute for proper logging. + +5. If you use asyncio.create_task, your tasks need to: + + - Be cancelled on cog unload. + - Handle errors. + +6. Event listeners should exit early if it is an event you don't need. + This makes your events less expensive in terms of CPU time. Examples below: + + - Checking that you are in a guild before interacting with config for an antispam command. + - Checking that you aren't reacting to a bot message (``not message.author.bot``) early on. + +7. Use .gitignore (or something else) to keep unwanted files out of your cog repo. +8. Put a license on your cog repo. + + - By default, in most jurisdictions, without a license that at least offers the code for use, + users cannot legally use your code. + +9. Use botwide features when they apply. Some examples of this: + + - ``ctx.embed_color`` + - ``bot.is_automod_immune`` + +10. Use checks to limit command use when the bot needs special permissions. +11. Check against user input before doing things. Common things to check: + + - Resulting output is safe. + - Values provided make sense. (eg. no negative numbers for payday) + - Don't unsafely use user input for things like database input. + +12. Don't abuse bot internals. + + - If you need access to something, ask us or open an issue. + - If you're sure the current usage is safe, document why, + but we'd prefer you work with us on ensuring you have access to what you need. + +13. Update your cogs for breakage. + + - We announce this in advance. + - If you need help, ask.