Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Red Discord Bot project relies on community contributions for bug fixes, feature enhancements, and documentation. These guidelines provide a structured workflow to streamline the contribution process and ensure code quality across Windows, macOS, and Linux platforms.
Sources: CONTRIBUTING.md:16-24, CONTRIBUTING.md:31-31
Ground Rules
You must follow specific standards to ensure your contribution is accepted into the project:
- Maintain cross-platform compatibility for Windows, macOS, and Linux.
- Use Python features compatible with version 3.8.1 and above.
- Write new tests for any added code or bug fixes.
- Open an issue to discuss new features before implementation.
- Obtain approval via an issue before adding new cogs.
- Follow the Python Community Code of Conduct.
Sources: CONTRIBUTING.md:31-41
Development Environment Setup
The project uses a standard set of tools to manage dependencies and environments. You must have Python 3.8.1+, git, and pip installed before starting.
Automated Setup
The project includes a Makefile to automate environment creation.
- Fork and clone the repository.
- Run
make newenvto create a virtual environment in the.venvdirectory. - Activate the environment:
- Posix:
source .venv/bin/activate - Windows:
.venv\Scripts\activate
- Posix:
Sources: CONTRIBUTING.md:54-72
Environment Management Commands
The following make recipes help manage your workspace:
| Command | Action |
|---|---|
make newenv | Creates a clean virtual environment and installs Red in editable mode. |
make syncenv | Synchronizes the environment with the latest dependencies. |
make reformat | Automatically reformats Python files using Black. |
make stylecheck | Checks if files require reformatting. |
Sources: CONTRIBUTING.md:99-106
Testing and Code Style
The project enforces strict testing and styling rules. Your Pull Request (PR) will not be merged until all automated tests pass.
Testing with Tox
The project uses tox to manage test environments. Tox executes the following stages:
- py38: Runs unit tests using
pytest. - docs: Verifies that documentation builds without warnings.
- style: Checks code against the style guide.
To run all tests, execute the tox command in the project directory.
Sources: CONTRIBUTING.md:79-91
Code Style
The project uses Black as the primary auto-formatter. The configuration is defined in pyproject.toml.
- Line Length: 99 characters (Exception to Black's default 88).
- Target Version: Python 3.8.
Sources: CONTRIBUTING.md:93-97, pyproject.toml:44-46
Contribution Workflow
The contribution process follows a standard branch-and-merge model facilitated by GitHub.
The diagram above shows the lifecycle of a contribution from forking to merging.
Sources: CONTRIBUTING.md:113-118
Code Review Process
A core team evaluates issues and PRs daily. Decisions are made by simple majority or by the project owner.
Pull Request Evaluation
- Submission: Submit your PR after passing local tests.
- Review: Core members test the PR (usually within one week).
- Owner Approval:
- Improvements: The owner has 1 day to veto after core approval.
- New Features: The owner has 1 week to veto after core approval.
- Finalization: If no veto occurs and no changes are requested, the PR is merged.
Sources: CONTRIBUTING.md:133-149
Reporting Vulnerabilities
You must not report security vulnerabilities through public issues. Use GitHub's private vulnerability reporting feature.
- Navigate to the security advisory section of the repository.
- Fill out the report form with a summary, details, and proof of concept.
- The team aims to respond within 7 days.
Sources: SECURITY.md:18-35
Release Management
Maintainers use the release_helper.py tool to coordinate releases. This script guides developers through different release types and automates changelog generation.
Release Types
The helper categorizes releases into four levels:
| Type | Description |
|---|---|
| Breaking | Significant changes, performed from V3/develop. |
| Standard | Features and bugfixes without breaking changes. |
| Maintenance | Cherry-picked enhancements and bugfixes on short-lived branches. |
| Hotfix | Quick patches for supported releases. |
Sources: tools/release_helper.py:35-41, tools/release_helper.py:214-230
Release Workflow
The ReleaseStage enum tracks the progress of a release through the following logical flow:
The diagram shows the automated and manual steps required to finalize a bot release.
Sources: tools/release_helper.py:44-58, tools/release_helper.py:461-467
Conclusion
Following these guidelines ensures that Red remains a stable, modular, and high-quality bot. By adhering to the testing, styling, and review protocols, contributors help the core team maintain a reliable software ecosystem for all users.
Sources: CONTRIBUTING.md:16-24, README.md:43-46