langfingaz/anki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update contrib file

Browse Source
This commit is contained in:
Damien Elmes 2020-01-15 14:26:50 +10:00
parent 72c06a4aef
commit fbd7d966ea
1 changed files with 40 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
README.contributing
View File

@ -20,25 +20,30 @@ 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.
bugs, and many addons currently rely on certain variable/method names and
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.
Please use type hints in any new code that you are contributing.
automated tools. At the moment, large parts of the codebase are still missing
type hints, and some of the hints that do exist are incorrect or too general.
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.
checks functions that have type signatures, so adding more type signatures to
the code increases the amount of code that mypy is able to analyze.
Patches that improve the type hints would be appreciated. And if you're
adding new functionality, please use type hints in the new code you write
where practical.
Parts of Anki's codebase use ad-hoc data structures like nested dictionaries
and lists, and they can be difficult to fully type. Don't worry too much about
getting the types perfect - even a partial type like Dict[str, Any] or
List[Tuple] is an improvement over no types at all.
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
@ -51,6 +56,29 @@ 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
Hooks
-------
If you're writing an add-on and would like to extend a function that doesn't
currently have a hook, a pull request that adds the required hooks would be
welcome. If you could mention your use case in the pull request, that would be
appreciated.
The GUI hooks try to follow a consistent naming format:
([module]) [subject] [passive verb]
For example, editor_context_menu_will_show, browser_row_did_change, etc. This
makes it easier to locate relevant hooks in autocomplete by typing a prefix.
Using "did" instead of the past test "changed" can seem awkward, but makes it
consistent with "will", and is similar to the naming style used in iOS's
libraries.
The hook code is automatically generated using the definitions in
pylib/tools/genhooks.py and qt/tools/genhooks_gui.py. Adding a new definition
in one of those files and running 'make develop' will update pylib/anki/hooks
.py or qt/aqt/gui_hooks.py.
Tests Must Pass
----------------