CopyBot/Red-DiscordBot
1
0
Fork 0
mirror of https://github.com/Cog-Creators/Red-DiscordBot.git synced 2025-11-06 03:08:55 -05:00
Code Issues Packages Projects Releases Wiki Activity
Red-DiscordBot/.github/CONTRIBUTING.md
Toby Harradine 461f56bca1
Kill Pipfile, update dependencies, and add dep bumping tools (#2806) 
### Replacement for pipenv's environment setup
First of all, there's a new Make recipe for all devs and contributors on both Windows and Posix, `make setupenv`, which is kind of a replacement for `pipenv install --dev`. It creates a virtual environment in `.venv` using the inbuilt `venv` module, clearing out any existing virtual environment if needed first. Then it installs all dev dependencies using our new `dev-requirements.txt` file. `CONTRIBUTING.md` has been updated to reflect all of this.

### Dependency version bumping tool
Secondly, I've added a python script, `tools/bumpdeps.py` to help with bumping dependency versions. It has its own Make recipe too, `make bumpdeps`. This script won't work on Windows (yet). It reads the `tools/primary_deps.ini` file, which contains the primary requirements of Red and its extras with loose version specifiers, and outputs all pinned dependencies, in `setup.cfg` format. It's not a foolproof dependency resolver, it's quite simple, but it's bound to help out a lot. It'll try to give warnings if there might be a version conflict, but updating `setup.cfg` with its output and then doing `pip install -r dev-requirements.txt` will allow pip to issue warnings if something is conflicting.

So to add a new dependency, add it to `tools/primary_deps.ini` in the appropriate place, and either use `make bumpdeps` to completely update all dependencies, or simply add it to `setup.cfg` manually with its sub-dependencies, and all versions pinned.

### Sphinx 2.1.2 (docs changes)
The sphinx update brought along the ability to disable type annotations being rendered in function and method signatures, and I have gladly gone and done that. Type annotations should already be specified under the "Parameters" section, and the way sphinx renders them in function signatures makes them much harder to read.

Also, documented classes will now display what classes they inherit from.

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
2019-06-28 00:16:14 +10:00

11 KiB
Raw Blame History

Contents

1. Introduction

Welcome! First off, thank you for contributing to the further development of Red. We're always looking for new ways to improve our project and we appreciate any help you can give us.

1.1 Why do these guidelines exist?

Red is an open source project. This means that each and every one of the developers and contributors who have helped make Red what it is today have done so by volunteering their time and effort. It takes a lot of time to coordinate and organize issues and new features and to review and test pull requests. By following these guidelines you will help the developers streamline the contribution process and save them time. In doing so we hope to get back to each and every issue and pull request in a timely manner.

1.2 What kinds of contributions are we looking for?

We love receiving contributions from our community. Any assistance you can provide with regards to bug fixes, feature enhancements, and documentation is more than welcome.

2. Ground Rules

We've made a point to use ZenHub (a plugin for GitHub) as our main source of collaboration and coordination. Your experience contributing to Red will be greatly improved if you go get that plugin.

  1. Ensure cross compatibility for Windows, Mac OS and Linux.
  2. Ensure all Python features used in contributions exist and work in Python 3.7 and above.
  3. Create new tests for code you add or bugs you fix. It helps us help you by making sure we don't accidentally break anything 😀
  4. Create any issues for new features you'd like to implement and explain why this feature is useful to everyone and not just you personally.
  5. Don't add new cogs unless specifically given approval in an issue discussing said cog idea.
  6. Be welcoming to newcomers and encourage diverse new contributors from all backgrounds. See Python Community Code of Conduct.

3. Your First Contribution

Unsure of how to get started contributing to Red? Please take a look at the Issues section of this repo and sort by the following labels:

  • beginner - issues that can normally be fixed in just a few lines of code and maybe a test or two.
  • help-wanted - issues that are currently unassigned to anyone and may be a bit more involved/complex than issues tagged with beginner.

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

At this point you're ready to start making changes. Feel free to ask for help; everyone was a beginner at some point!

4. Getting Started

Red's repository is configured to follow a particular development workflow, using various reputable tools. We kindly ask that you stick to this workflow when contributing to Red, by following the guides below. This will help you to easily produce quality code, identify errors early, and streamline the code review process.

4.1 Setting up your development environment

The following requirements must be installed prior to setting up:

  • Python 3.7.0 or greater
  • git
  • pip

If you're not on Windows, you should also have GNU make installed, and you can optionally install pyenv, which can help you run tests for different python versions.

  1. Fork and clone the repository to a directory on your local machine.
  2. Open a command line in that directory and execute the following command: 
    make setupenv
    Red, its dependencies, and all required development tools, are now installed to a virtual environment located in the .venv subdirectory. Red is installed in editable mode, meaning that edits you make to the source code in the repository will be reflected when you run Red.
  3. Activate the new virtual environment with one of the following commands:
    • Posix: 
      source .venv/bin/activate
    • Windows: 
      .venv\Scripts\activate
    Each time you open a new command line, you should execute this command first. From here onwards, we will assume you are executing commands from within this activated virtual environment.

Note: If you're comfortable with setting up virtual environments yourself and would rather do it manually, just run pip install -r dev-requirements.txt after setting it up.

4.2 Testing

We've recently started using tox to run all of our tests. It's extremely simple to use, and if you followed the previous section correctly, it is already installed to your virtual environment.

Currently, tox does the following, creating its own virtual environments for each stage:

  • Runs all of our unit tests with pytest on python 3.7 (test environment py37)
  • Ensures documentation builds without warnings, and all hyperlinks have a valid destination (test environment docs)
  • Ensures that the code meets our style guide with black (test environment style)

To run all of these tests, just run the command tox in the project directory.

To run a subset of these tests, use the command tox -e <env>, where <env> is the test environment you want tox to run. The test environments are noted in the dot points above.

Your PR will not be merged until all of these tests pass.

4.3 Style

Our style checker of choice, black, actually happens to be an auto-formatter. The checking functionality simply detects whether or not it would try to reformat something in your code, should you run the formatter on it. For this reason, we recommend using this tool as a formatter, regardless of any disagreements you might have with the style it enforces.

Use the command black --help to see how to use this tool. The full style guide is explained in detail on black's GitHub repository. There is one exception to this, however, which is that we set the line length to 99, instead of black's default 88. When using black on the command line, simply use it like so: black -l 99 -N <src>.

4.4 Make

You may have noticed we have a Makefile and a make.bat in the top-level directory. For now, you can do three things with them:

  1. make reformat: Reformat all python files in the project with Black
  2. make stylecheck: Check if any .py files in the project need reformatting
  3. make setupenv: Set up a new virtual environment in the .venv subdirectory, and install Red and its dependencies. If one already exists, it is cleared out and replaced.

4.5 Keeping your dependencies up to date

Whenever you pull from upstream (V3/develop on the main repository) and you notice either of the files setup.cfg or dev-requirements.txt have been changed, it can often mean some package dependencies have been updated, added or removed. To make sure you're testing and formatting with the most up-to-date versions of our dependencies, run make setupenv to recreate your virtual environment. You could also simply do pip install -Ur dev-requirements.txt, but you will still have any dependencies which may have been removed previously.

4.6 To contribute changes

  1. Create a new branch on your fork
  2. Make the changes
  3. If you like the changes and think the main Red project could use it:
    • Run tests with tox to ensure your code is up to scratch
    • Create a Pull Request on GitHub with your changes

4.7 How To Report A Bug

Please see our ISSUES.MD for more information.

4.8 How To Suggest A Feature Or Enhancement

The goal of Red is to be as useful to as many people as possible, this means that all features must be useful to anyone and any server that uses Red.

If you find yourself wanting a feature that Red does not already have, you're probably not alone. There's bound to be a great number of users out there needing the same thing and a lot of the features that Red has today have been added because of the needs of our users. Open an issue on our issues list and describe the feature you would like to see, how you would use it, how it should work, and why it would be useful to the Red community as a whole.

5. Code Review Process

We have a core team working tirelessly to implement new features and fix bugs for the Red community. This core team looks at and evaluates new issues and PRs on a daily basis.

The decisions we make are based on a simple majority of that team or by decree of the project owner.

5.1 Issues

Any new issues will be looked at and evaluated for validity of a bug or for the usefulness of a suggested feature. If we have questions about your issue we will get back as soon as we can (usually in a day or two) and will try to make a decision within a week.

5.2 Pull Requests

Pull requests are evaluated by their quality and how effectively they solve their corresponding issue. The process for reviewing pull requests is as follows:

  1. A pull request is submitted
  2. Core team members will review and test the pull request (usually within a week)
  3. After a majority of the core team approves your pull request:
    • If your pull request is considered an improvement or enhancement the project owner will have 1 day to veto or approve your pull request.
    • If your pull request is considered a new feature the project owner will have 1 week to veto or approve your pull request.
  4. If any feedback is given we expect a response within 1 week or we may decide to close the PR.
  5. If your pull request is not vetoed and no core member requests changes then it will be approved and merged into the project.

5.3 Differences between "new features" and "improvements"

The difference between a new feature and improvement can be quite fuzzy and the project owner reserves all rights to decide under which category your PR falls.

At a very basic level a PR is a new feature if it changes the intended way any part of the Red project currently works or if it modifies the user experience (UX) in any significant way. Otherwise, it is likely to be considered an improvement.

6. Community

You can chat with the core team and other community members about issues or pull requests in the #coding channel of the Red support server located here.