From 2e7669daf49ad2818ba458fca711e69b3cee36a4 Mon Sep 17 00:00:00 2001 From: Damien Elmes Date: Thu, 2 Jan 2020 19:55:27 +1000 Subject: [PATCH] update docs --- LICENSE | 1 + README.contributing | 113 ++++++++++++++++++++++++++++++++++++++++++++ README.development | 77 ++++++++++++++++++++++++++++++ README.md | 10 +++- 4 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 LICENSE create mode 100644 README.contributing create mode 100644 README.development diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..97e2a1deb --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +Primarily GNU AGPL3+ - please see the LICENSE file in each subfolder. diff --git a/README.contributing b/README.contributing new file mode 100644 index 000000000..b40b1c155 --- /dev/null +++ b/README.contributing @@ -0,0 +1,113 @@ +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. diff --git a/README.development b/README.development new file mode 100644 index 000000000..fabcad9e1 --- /dev/null +++ b/README.development @@ -0,0 +1,77 @@ +TODO: translations + +For non-developers who want to try this development code, the easiest way is +to use a binary package - please see: + +https://anki.tenderapp.com/discussions/beta-testing + +You are welcome to run Anki from source instead, but it is expected that you +can sort out all dependencies and issues by yourself - we are not able to +provide support for problems you encounter when running from source. + +To start, make sure you have the following installed: + + - Python 3.6+ + - portaudio + - mpv + - lame + - npm + - your platform's C compiler, eg gcc, Xcode or Visual Studio 2017. + - GNU make + - protoc v3 (https://github.com/protocolbuffers/protobuf/releases) + - rustup (https://rustup.rs/) + +The build scripts assume a UNIX-like environment, so on Windows you will +need to use WSL or Cygwin to use them. + +Once you've installed the above components, execute ./run in this repo, +which will build the subcomponents, and start Anki. + +Before contributing code, please read README.contributing. + +If you'd like to contribute translations, please see the translations section +of http://ankisrs.net/docs/manual.html#_contributing + +Subcomponents +-------------- + +- proto contains the interface used to communicate between the Rust and + Python code. +- lib-rust contains the parts of the code implemented in Rust. This + is only a tiny subsection at the moment. +- lib-rspy contains a Python module (ankirspy) for accessing the Rust code. +- lib-python contains a Python module (anki) that covers all of the work + not related to the user interface. +- anki-qt contains the Qt GUI implementation (aqt). + +Helper scripts +-------------- + +There are some helper scripts in this folder: + +run: builds Anki and runs it in place. Command line arguments will be passed +on to Anki. + +bundle: builds the subcomponents into binary wheels stored in the build/ folder. + +check: runs tests on each of the subcomponents. + +fix: fix any code formatting issues in the subcomponents. + +clean: remove generated build files and force a (mostly) full rebuild on the +next run/check. + +PyQt +----- + +The build scripts will use PyQt/Qt from Pypi by default. If you wish to use a +system install, you will need to set up the pyenv folder yourself, making sure +you have PyQt5, the WebEngine module and development tools (eg pyqt5-dev-tools) +installed as well. You'll need to create the venv with --system-site-packages. + +Mac users +---------- + +You can use homebrew to install some dependencies: + +$ brew install python mpv lame portaudio protobuf npm rustup-init diff --git a/README.md b/README.md index fb00b97b8..82688cba2 100644 --- a/README.md +++ b/README.md @@ -1 +1,9 @@ -[update coming soon] +This repo contains all the code for the computer version of Anki. + +If you'd like to try development builds of Anki but don't feel comfortable +building the code, please see +https://anki.tenderapp.com/discussions/beta-testing + +For more information on building, please see README.development + +If you'd like to contribute code, please see README.contributing