GitHub/Anki
1
0
Fork 0
mirror of https://github.com/ankitects/anki.git synced 2025-09-20 23:12:21 -04:00
Code Issues Projects Releases Packages 1 Wiki Activity Actions

update readme

Browse source
This commit is contained in:
Damien Elmes 2020-01-07 21:45:44 +10:00
parent 4fc6184f80
commit fb5e6f3d01
1 changed files with 36 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

91
README.contributing
View file

@ -4,38 +4,26 @@ Contributing Code
For info on contributing things other than code, such as translations, decks For info on contributing things other than code, such as translations, decks
and add-ons, please see http://ankisrs.net/docs/manual.html#contributing 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, With most users now on 2.1, it's time to start paying down some of the
while maintaining compatibility with Anki 2.0.x. Some users will be stuck on technical debt that Anki's codebase has built up over the years. This is
Anki 2.0 for a while due to unported add-ons or old hardware, so it's not an easy task - the code is tightly coupled together, not fully covered
important that 2.1 doesn't make breaking changes to the file format. 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 So to start with, the primary focus is on changes that will make future
clients, which try their best to keep as close to the Anki code as possible so maintenance and refactoring easier - improving tooling and linting, static
that future updates can be ported more easily. Refactoring code makes it type checking, more unit tests, and so on. Contributions that move the code in
harder for the mobile clients to track changes, so refactoring should be this direction or fix bugs would be appreciated.
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 If you would like to add a new feature or alter existing functionality in the
increase your chances of the changes being accepted. 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 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
Small patches that fix a specific problem and don't affect other functionality changes may be accepted, but larger changes are less likely to be at this
are likely to be merged if they meet the other requirements below. Larger time.
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
----------- -----------
@ -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 there are parts that are difficult to type properly. Don't feel the need to
avoid 'Any' when a proper type is impractical. avoid 'Any' when a proper type is impractical.
When adding type signatures, please avoid refactoring the code, as this is When running 'make check', Anki uses mypy to typecheck the code. Mypy only
liable to break add-ons or introduce regressions. 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, Anki bundles Qt stubs, but they are not perfect, so you'll find when doing
but not very good at type inference, so it is mostly useful for checking code things like connecting signals, you may have to add the following to the end
that has type signatures. It is able to read the bundled Qt stubs, and works of a line to silence the spurious errors.
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 # type: ignore
@ -68,13 +52,16 @@ https://github.com/dae/anki/commit/ed0b3d337458d7161811547932b6476f2d4bc887
Tests Must Pass Tests Must Pass
---------------- ----------------
Please make sure './check' in the anki repo completes successfully before Please make sure 'make check' completes successfully before submitting code.
submitting code. You can do this automatically by adding the following into You can do this automatically by adding the following into
.git/hooks/pre-push and making it executable. .git/hooks/pre-commit or .git/hooks/pre-push and making it executable.
#!/bin/bash #!/bin/bash
set -e 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 If your change is to anki/ and not covered by the existing unit tests, please
consider adding a unit test at the same time. 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 You are welcome to use snake_case variable names and functions in newly
introduced code, but please avoid renaming existing variables and functions introduced code, but please avoid renaming existing functions and global
that use camelCaps. 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. Code formatting is automatically done when you use "make fix".
You can fix the formatting automatically with 'make fixpyfmt'.
Do One Thing Do One Thing
------------- -------------
@ -100,11 +88,4 @@ requests instead.
License License
------- -------
Please add yourself to the contributors file in your first pull request. 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.