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

With most users now on 2.1, it's time to start paying down some of the
technical debt that Anki's codebase has built up over the years. This is
not an easy task - the code is tightly coupled together, not fully covered
by unit tests, and mostly dynamically typed, meaning even small changes
carry the risk of regressions.

So to start with, the primary focus is on changes that will make future
maintenance and refactoring easier - improving tooling and linting, static
type checking, more unit tests, and so on. Contributions that move the code in
 this direction or fix bugs would be appreciated.

If you would like to add a new feature or alter existing functionality in the
Python code, please reach out on the support site before you begin work, as
some changes may be more appropriately done in an add-on instead.

Please hold off on large refactoring projects for now, as it risks introducing
bugs and breaking add-ons that depend on certain type signatures. If you're
working on an isolated part of the codebase covered by unit tests, then such
changes may be accepted, but larger changes are less likely to be at this
time.

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 running 'make check', Anki uses mypy to typecheck the code. Mypy only
checks parts of the code that have type signatures, so adding more type
signatures to the code improves code coverage.

Anki bundles Qt stubs, but they 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 'make check' completes successfully before submitting code.
You can do this automatically by adding the following into
.git/hooks/pre-commit or .git/hooks/pre-push and making it executable.

#!/bin/bash
set -e
make check

You may need to adjust the PATH variable so that things like a local install
of cargo can be found.

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 functions and global
variables that use camelCaps. Variables local to a function are safer to
rename, but please do so only when a function needs to be changed for other
reasons as well.

Code formatting is automatically done when you use "make fix".

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.