update readme

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.