Skip to content

Latest commit

 

History

History
137 lines (76 loc) · 8.25 KB

CONTRIBUTING.md

File metadata and controls

137 lines (76 loc) · 8.25 KB
Raw

How to Contribute to my Anki Add-ons

👋 Hi! Thanks for deciding to contribute! The following document tries to summarize all of the different ways in which you can support the development of my add-ons, be it as an end-user or programmer.

Table of Contents

Supporting my Work Directly

Are you eager to contribute, but don't have the ability/time to work on the project yourself? Then please consider using one of the buttons below to support my efforts by pledging your support on Patreon, or by buying me a coffee. Each and every contribution is greatly appreciated and will help me maintain and improve my Anki add-ons as time goes by!

    

Thank you!

Reporting a Bug or Suggesting a New Feature

This section guides you through submitting bug reports and feature requests. Following these guidelines helps the community and me to understand your report, reproduce the behavior, and find related reports.

Note: Most of the actions below require that you sign up to GitHub. Registration only takes a moment and allows you to participate in the development of all of your favorite Anki add-ons (not just mine!).

Using the issue tracker on GitHub is the fastest way to get in touch with me, as I don't get notified of your reviews or forum posts. It also greatly reduces my workload because formalities such as checking for existing reports and asking for debug information are automatically taken care of.

You can also contact me by submitting a new thread on Anki's αdd-on support forums, or messaging me at [email protected], but the issue tracker is the fastest way to get my attention.

Here is how you would ideally report a bug or suggest new feature:

  1. Start by clicking on the issues tab of the repository in question.:

    If you don't know how to find the repository of a particular add-on: It's usually linked at the bottom of the description text on AnkiWeb (just search for 'github' on the page).

  2. Next, please ensure that the bug or suggestion has not been submitted before by performing a cursory search through the existing issues:

  3. If you're unable to find an open issue, click on New Issue to open a new one:

  4. If there are multiple issue types, click Get started next to the type of issue you'd like to open:

  5. Make sure to fill out the provided description template as best as you can, and enter a descriptive title that concisely summarizes the issue.

  6. When you're finished, click Submit new issue.

Contributing to the Codebase

Scope of Changes

Reviewing and testing outside changes takes time. A patch or pull request should therefore be the minimum necessary to address one issue. Please don't make a pull request for a bunch of unrelated changes, as they are likely to be rejected – split them up into separate requests instead.

Small patches that fix a specific problem and don't affect other functionality are more likely to be merged than broader changes that affect many parts of the code. If in doubt, please ask before you begin work on them so your work does not go to waste. The easiest way to get in touch with me is opening an issue in the corresponding repository and, when prompted, selecting the Question option.

It is important that your changes maintain the same level of compatibility as the existing code. For add-ons that support both Anki 2.0 and 2.1, you will have to refrain from using any features or idioms only supported by Python 3, Qt 5, or Anki 2.1.

You can find out which level of compatibility the add-on currently supports by looking at the targets key in the addon.json file at the very top of the repository. Should the repository not include an addon.json file, then please try to follow whatever compatibility specifications are noted on the AnkiWeb page of the add-on (usually linked at the top of the repository).

Coding Style Conventions

Overview

For consistency, changes should maintain the existing code style that is inspired by Anki's code base:

  • < 80 column lines
  • succint variable names
  • naming conventions: camelCase for function and method names. PascalCase for class names. snake_case for other variables.
  • outside of that: general adherence to PEP8

Linting

Before submitting your changes, I recommend running them through a linter like flake8. The following command should more or less reflect the coding conventions listed above:

flake8 --ignore=F405,F408,F403,E302,E303,E305,W293,N802,E266,N806,E226,E402 --exclude=forms,resources src

If you prefer pylint, feel free to run it against the configuration Anki uses.

Submitting a Pull Request

  1. Fork the repository and clone it to your local disk

  2. On your local copy of the repository, switch to the main development branch (if not otherwise noted this is the master branch):

     $ cd <repo_name>
 $ git checkout master

  3. Create a branch to hold your changes and start making changes. Do not work on the master branch!

      $ git checkout -b my-feature

  4. When tracking your changes through commits, please follow these guidelines:

    • Concisely summarize your changes with informative commit messages. For a general guide on writing commit messages please see here.
    • Try to limit your commits to a minimum amount to avoid crowding up the revision history.
    • If you can sensibly group the changes under one commit (i.e. squash them), please do so.

  5. Push your changes to GitHub with

     $ git push -u origin my-feature

  6. Create a pull request with your changes

  7. If you are presented with a description template, try to fill it out as best as you can. Otherwise try to succinctly summarize the problem you're addressing and the scope of your changes. Should your PR address an existing issue report, please link to it.

  8. Add a descriptive title that summarizes your changes at a glance.

  9. Submit your pull request for review.

For more information on working with Git and GitHub please see GitHub's help center.

Parts of this document were inspired by Anki's contribution guidelines.