92 lines
3.6 KiB
Plaintext
92 lines
3.6 KiB
Plaintext
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.
|