113 lines
4.6 KiB
Plaintext
113 lines
4.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
|
|
|
|
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 Anki codebase.
|
|
|
|
You can optionally use 'make pytype' to typecheck the code with pytype. Pytype
|
|
is much slower, but it can catch errors in untyped code that mypy misses. It
|
|
is not able to check the aqt/* code, as it can't read the Qt stubs, and it is
|
|
not currently compatible with Python 3.8. It can be difficult to build on
|
|
some platforms.
|
|
|
|
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 'make check' completes successfully before submitting code.
|
|
|
|
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
|
|
-------
|
|
|
|
As mentioned in the LICENSE file, we are only able to accept non-trivial
|
|
patches or pull requests from people who have sent us a private message
|
|
indicating that they license their changes under the BSD license.
|
|
|
|
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.
|