diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1d324bde --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,158 @@ +# Contributing to Pax-Academia + +Pax Academia is an open source project, and we welcome contributions of all kinds from anyone. As this project has grown to become a large project, we have implemented some guidelines to ensure that the project remains maintainable and that contributions are of high quality. + +This document outlines the process for contributing to the project. Please read it carefully before making a contribution so that you know what to expect and what is expected of you. + +## 1. Non Contributors + +If you are not listed as a contributor, you are still welcome to help out! +Please fork the repository and make a pull request with your changes. +Follow the guidelines below to ensure your pull request is correct. Incorrect pull requests will be rejected. + +## 2. Contributors + +Please create your own branch and make a pull request to the master branch. +Follow the guidelines below to ensure your pull request is correct. Incorrect pull requests will be rejected. + +## 3. Pull Request Guidelines + +### 3.1 Branch Names + +Please name your branch as follows: +`.` + +### 3.2 Commit Messages/ Commits + +- Use the present tense ("Add feature" not "Added feature") +- Keep messages short and concise +- Keep commits small and concise (commit regularly) + +### 3.3 Pull Requests + +#### 3.3.1 Title +Your title should be short and concise. It should be in the format: +`: ` +where `` is one of the following: +- `feat` (feature) +- `fix` (bug fix) +- `docs` (documentation) +- `style` (formatting, missing semi colons, etc; no code change) +- `refactor` (refactoring production code) +- `test` (adding missing tests, refactoring tests; no production code change) +- `chore` (updating grunt tasks etc; no production code change) + +and `` is a short description of the changes made. + +#### 3.3.2 Description +Your description is where you can go into more detail about your changes. +Please include _at least_ the following: +- What you changed +- Why you changed it + +If your PR is related to an issue, please include the issue number in the description. +If it solves the issue, please include `Closes #` in the description. This will automatically close the issue when the PR is merged. + +#### 3.3.3 Labels +Each PR MUST have at least one label. The following labels are available: +- `bugfix` (bug fix) => PR's with this label must have a corresponding issue +- `enhancement` (existing feature) +- `documentation` (documentation) +- `dependencies` (Updates a dependency) +- `feature` (new feature) +- `hotfix` (very small bugfix/typo fix) +- `refactor` (refactoring production code) + +(PR's with no label will be rejected) + +#### 3.3.4 Content +A PR may not contain code and commits not related to the issue it is solving or feature it is completing. +F.ex. +- a PR solving issue #1 may not contain code or commits related to issue #2. +- Do not include a commit that changes something in the docs when working on a discord command (unless the docs are related to the command) +- Do not refactor code in cog A when working on cog B +- ... + + +## 4. Code Guidelines + +### 4.1 PEP8 + +Please follow the PEP8 style guide. To do so, please use the [black](https://pypi.org/project/black/) python formatter. +(All code in this repository is formatted using black) + +### 4.2 Documentation + +#### 4.2.1 Docstrings +Please include docstrings for all functions and classes. These do not have to be long, +but at least include the basic information (what the function does, what the parameters are, what the return value is, etc). + +#### 4.2.2 Comments +Please include comments where necessary. This includes: +- Comments explaining complex code +- Comments explaining why you did something a certain way + +#### 4.2.3 Type Hints +Please include type hints for all functions and classes. + +### 4.3 Complexity + +Please keep your code as simple as possible. We prefer longer, simpler code over shorter, more complex code. +Avoid long list comprehensions, complex lambda functions, etc. + +### 4.4 Imports + +Please keep your imports as simple as possible. Avoid importing entire modules, and avoid importing multiple modules on one line. + +> [!IMPORTANT] +> If you wish to use an external library, please ask first. We want to keep the number of external libraries to a minimum. +(using external libraries already included in the requirements.txt is fine). + +> [!WARNING] +> @sebastiaan-daniels must review external libraries for security vulnerabilities before they can be used. + + +## 5. Reviewing Guidelines + +### 5.1 Code Reviews from contributors + +Each contributor, regardless of their role, is allowed to review code. +However, requested changes or comments made by contributors do not have to be followed by the author of the PR. They are merely suggestions. + +### 5.2 Code Reviews from maintainers (Code Owners) + +#### 5.2.1 General +Each PR, depending on its complexity, must be reviewed by at least n maintainers. (see 5.2.3 for the number of maintainers required for each type of PR) +No code may be merged without the approval of those code owners. All code owners must be requested to review the PR. (this should be done automatically by github) + +#### 5.2.2 Code Owners +The project maintainers (owners), are the people listed under `.github/CODEOWNERS`. + +#### 5.2.3 Reviewing +For each type of PR, the following amount of code owners must approve the PR before merging: +- `hotfix` => 1 +- `documentation` => 1 +- `dependencies` => 1 + @sebastiaan-daniels +- `bugfix` => 2 +- `refactor` => 2 +- `enhancement` => 3 +- `feature` => 4 + +#### 5.2.4 Accepted code +If the required number of code owners have approved the PR, the PR may be merged by any code owner. + +#### 5.2.5 Changes requested by a code owner +If any code owner requests changes, (regardless whether or not the required number of code owners have approved the PR), the PR may not be merged until those changes have been either made or discussed and agreed upon. + +The code owner that requested changes must re-review the PR and approve it before it can be merged. + +### 5.3 PR's from code owners + +#### 5.3.1 General +If a code owner makes a PR, the same rules apply as for any other contributor. The PR must be reviewed by the required number of code owners, and may not be merged until the required number of code owners have approved the PR. + +#### 5.3.2 Special cases + +Since a user cannot review their own PR, there are some cases in which more code owners must review the PR than there are existing. +In these cases, if all code owners have approved the PR, the PR may be merged by any code owner. +I.e if a code owner creates a feature, only 3 code owners must add a review. (since there are only 4 owners.) \ No newline at end of file diff --git a/README.md b/README.md index e1f3cefa..03ba57f1 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,7 @@ General purpose utility bot for the Homework Help Discord server ## How to Contribute -1. Fork this repository into your own account. - - Check out the [cogs](./cogs/README.md) folder for in progress cogs that you can contribute to. - - Check out [this](./ENVIRONMENT.md) on setting up the environment. -2. Commit changes to your fork. -3. Open a pull request, making sure to comapre across forks. - - For more information regarding pull requests across forks, please check out GitHub's official docs [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). +To contribute to this project, please read the [Contributing Guidelines](./CONTRIBUTING.md). ## Running bot diff --git a/cogs/moderation.py b/cogs/moderation.py index 166d75e2..bd55440f 100644 --- a/cogs/moderation.py +++ b/cogs/moderation.py @@ -34,13 +34,13 @@ class MessageFingerprint: attachment_urls: list[ str ] # the discord content URLs for each of the message's uploaded attachments - cached_attachment_hashes: set[ - Hash - ] | None = None # populated on the first call to `get_attachment_hashes` + cached_attachment_hashes: ( + set[Hash] | None + ) = None # populated on the first call to `get_attachment_hashes` - content_hash: Hash | None = ( - None # hash of the message body, after being passed through `filter_content` - ) + content_hash: ( + Hash | None + ) = None # hash of the message body, after being passed through `filter_content` # shortcut to build a fingerprint given a message @classmethod @@ -166,11 +166,8 @@ async def is_multipost_of(self, other: MessageFingerprint) -> bool: class Moderation(commands.Cog): def __init__(self, bot: commands.Bot) -> None: self.bot = bot - self.fingerprints: list[ - MessageFingerprint - ] = ( - [] - ) # stores all user messages sent in the last minute (recent messages near the end) + # stores all user messages sent in the last minute (recent messages near the end) + self.fingerprints: list[MessageFingerprint] = [] self.multipost_warnings: dict[ Annotated[int, "Multiposted Message ID"], tuple[ diff --git a/cogs/pubchem.py b/cogs/pubchem.py index 64a67a27..d922bb5c 100644 --- a/cogs/pubchem.py +++ b/cogs/pubchem.py @@ -1,6 +1,7 @@ from __future__ import annotations import asyncio +import string import pubchempy as pcp from discord import ApplicationContext, option @@ -49,7 +50,7 @@ def to_subscript(self, number: str) -> str: :type number: int :return: The subscripted version of the number. """ - return number.translate(str.maketrans("0123456789", "₀₁₂₃₄₅₆₇₈₉")) + return number.translate(str.maketrans(string.digits, "₀₁₂₃₄₅₆₇₈₉")) @commands.slash_command( name="chemsearch", diff --git a/cogs/staffapps_frontend.py b/cogs/staffapps_frontend.py index f58b9c75..a66c4f85 100644 --- a/cogs/staffapps_frontend.py +++ b/cogs/staffapps_frontend.py @@ -593,7 +593,7 @@ async def apply(self, ctx: discord.ApplicationContext) -> None: # check app status status = any( - x in [1, 3, 4, 5, 6, 7, 8] for x in applicant.status + x in (1, 3, 4, 5, 6, 7, 8) for x in applicant.status ) # 2 and 8 are closed applications, others are open if status: await ctx.respond(embed=embeds().ongoing(), ephemeral=True)