diff --git a/README.contributing b/README.contributing index 31da7bd1f..6b0684409 100644 --- a/README.contributing +++ b/README.contributing @@ -4,38 +4,26 @@ 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. +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. -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. +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. -Before sending a pull request or a patch, please check the following to -increase your chances of the changes being accepted. +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. -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. +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 ----------- @@ -46,17 +34,13 @@ 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 only +checks parts of the code that have type signatures, so adding more type +signatures to the code improves code coverage. -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. +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 @@ -68,13 +52,16 @@ 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. +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 -./check +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. @@ -83,11 +70,12 @@ 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. +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. -If your code isn't formatted correctly, 'make check' will report problems. -You can fix the formatting automatically with 'make fixpyfmt'. +Code formatting is automatically done when you use "make fix". Do One Thing ------------- @@ -100,11 +88,4 @@ 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. +Please add yourself to the CONTRIBUTORS file in your first pull request.