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 before sending a pull request for other components: https://github.com/ankitects/anki-contributors 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.