anki/README.contributing

Contributing Code
==================

For info on contributing things other than code, such as translations, decks
and add-ons, please see http://ankisrs.net/docs/manual.html#contributing

The goal of Anki 2.1.x is to bring Anki up to date with Python 3 and Qt 5,
while maintaining compatibility with Anki 2.0.x. Some users will be stuck on
Anki 2.0 for a while due to unported add-ons or old hardware, so it's
important that 2.1 doesn't make breaking changes to the file format.

Also of consideration is that the Anki code is indirectly used by the mobile
clients, which try their best to keep as close to the Anki code as possible so
that future updates can be ported more easily. Refactoring code makes it
harder for the mobile clients to track changes, so refactoring should be
limited to times when it is necessary to address an important issue.

Before sending a pull request or a patch, please check the following to
increase your chances of the changes being accepted.

Primarily Bugfixes
-------------------

Small patches that fix a specific problem and don't affect other functionality
are likely to be merged if they meet the other requirements below. Larger
changes are less likely to be accepted for 2.1.x - if in doubt, please ask
before you begin work on them so your work does not go to waste.

Examples of changes that are unlikely to be accepted:

- Altering existing code unnecessarily. Your code may be more elegant than
  what already exists, but it takes time for us to review the changes, may
  harbour unnoticed bugs, and makes maintaining the mobile clients more
  difficult.
- Adding code that is not used within Anki but is only for the benefit of
  add-ons - such code is difficult to test and maintain.
- Adding code that addresses niche issues - they are better handled in an
  add-on.

Type hints
-----------

Type hints have recently been added to parts of the codebase, mainly using
automated tools. Patches that improve the type hints are welcome, but
pragmatism is advised. Anki's codebase is old and of varying quality, and
there are parts that are difficult to type properly. Don't feel the need to
avoid 'Any' when a proper type is impractical.

When adding type signatures, please avoid refactoring the code, as this is
liable to break add-ons or introduce regressions.

When running 'make check', Anki uses mypy to typecheck the code. Mypy is fast,
but not very good at type inference, so it is mostly useful for checking code
that has type signatures. It is able to read the bundled Qt stubs, and works
across the whole Python codebase.

The Qt stubs are not perfect, so you'll find when doing things like connecting
signals, you may have to add the following to the end of a line to silence
the spurious errors.

 # type: ignore

In cases where you have two modules that reference each other, you can't simply
import the types from each module into the other one, as it can cause a cyclic
import. An example of how to work around this can be seen at
https://github.com/dae/anki/commit/ed0b3d337458d7161811547932b6476f2d4bc887

Tests Must Pass
----------------

Please make sure './check' in the anki repo completes successfully before
submitting code. You can do this automatically by adding the following into
.git/hooks/pre-push and making it executable.

#!/bin/bash
set -e
./check

If your change is to anki/ and not covered by the existing unit tests, please
consider adding a unit test at the same time.

Code Style
------------------

You are welcome to use snake_case variable names and functions in newly
introduced code, but please avoid renaming existing variables and functions
that use camelCaps.

If your code isn't formatted correctly, 'make check' will report problems.
You can fix the formatting automatically with 'make fixpyfmt'.

Do One Thing
-------------

A patch or pull request should be the minimum necessary to address one issue.
Please don't make a pull request for a bunch of unrelated changes, as they are
difficult to review and will be rejected - split them up into separate
requests instead.

License
-------

Please add yourself to the contributors file in your first pull request.

Add-ons
========

If you'd like to make more extensive changes, please consider writing an
add-on instead, as add-ons have none of these restrictions and can implement
whatever functionality in whatever style you wish.