README.contributing
1Contributing Code
2==================
3
4For info on contributing things other than code, such as translations, decks
5and add-ons, please see http://ankisrs.net/docs/manual.html#contributing
6
7The goal of Anki 2.1.x is to bring Anki up to date with Python 3 and Qt 5,
8while maintaining compatibility with Anki 2.0.x. Some users will be stuck on
9Anki 2.0 for a while due to unported add-ons or old hardware, so it's
10important that 2.1 doesn't make breaking changes to the file format.
11
12Also of consideration is that the Anki code is indirectly used by the mobile
13clients, which try their best to keep as close to the Anki code as possible so
14that future updates can be ported more easily. Refactoring code makes it
15harder for the mobile clients to track changes, so refactoring should be
16limited to times when it is necessary to address an important issue.
17
18Before sending a pull request or a patch, please check the following to
19increase your chances of the changes being accepted.
20
21Primarily Bugfixes
22-------------------
23
24Small patches that fix a specific problem and don't affect other functionality
25are likely to be merged if they meet the other requirements below. Larger
26changes are less likely to be accepted for 2.1.x - if in doubt, please ask
27before you begin work on them so your work does not go to waste.
28
29Examples of changes that are unlikely to be accepted:
30
31- Altering existing code unnecessarily. Your code may be more elegant than
32 what already exists, but it takes time for us to review the changes, may
33 harbour unnoticed bugs, and makes maintaining the mobile clients more
34 difficult.
35- Adding code that is not used within Anki but is only for the benefit of
36 add-ons - such code is difficult to test and maintain.
37- Adding code that addresses niche issues - they are better handled in an
38 add-on.
39
40Maintaining Style
41------------------
42
43For consistency, changes should maintain the existing code style - camelCaps,
44<80 column lines, succinct variable names and so on.
45
46Tests Must Pass
47----------------
48
49Please check that tools/tests.sh passes all tests prior to submitting a
50change. If your change is not covered by existing tests, ideally you'll add a
51new test.
52
53Do One Thing
54-------------
55
56A patch or pull request should be the minimum necessary to address one issue.
57Please don't make a pull request for a bunch of unrelated changes, as they are
58difficult to review and will be rejected - split them up into separate
59requests instead.
60
61License
62-------
63
64As mentioned in the LICENSE file, we are only able to accept non-trivial
65patches or pull requests from people who have sent us a private message
66indicating that they license their changes under the BSD license.
67
68Add-ons
69========
70
71If you'd like to make more extensive changes, please consider writing an
72add-on instead, as add-ons have none of these restrictions and can implement
73whatever functionality in whatever style you wish.
74
README.development
1Running from source
2--------------------
3
4For non-developers who want to try this development code, the easiest way is
5to use a binary package - please see:
6
7https://anki.tenderapp.com/discussions/beta-testing
8
9You are welcome to run Anki from source instead, but it is expected that you
10can sort out all dependencies and issues by yourself - we are not able to
11provide support for problems you encounter when running from source.
12
13Anki requires:
14
15 - Python 3.6+
16 - Qt 5.9.x/5.11.x/5.12.x and a PyQT that supports it
17 - mpv
18 - lame
19
20It also requires a number of Python packages, which you can grab via pip:
21
22$ pip3 install -r requirements.txt
23
24If you're on a Linux distribution that packages a compatible Qt then you can
25use the distro's packages. Make sure you install the development tools (eg
26pyqt5-dev-tools) as well.
27
28If you're on another platform or your distro has the wrong Qt version, you
29can install PyQt with pip:
30
31$ pip3 install PyQt5 PyQtWebEngine
32
33To use the development version:
34
35$ git clone https://github.com/dae/anki.git
36$ cd anki
37$ ./tools/build_ui.sh
38
39If you get any errors, you will not be able to proceed, so please return to
40the top and check the requirements again.
41
42ALL USERS: Make sure you rebuild the UI every time you git pull, otherwise you
43will get errors down the road.
44
45If you want to use a language other than English, copy the locale/ folder
46from a source tarball into the root of the repo.
47
48And now you're ready to run Anki:
49$ ./runanki
50
51If you get any errors, please make sure you don't have an older version of
52Anki installed in a system location.
53
54To run the unit tests, you will need to install nose and mock from your
55distro, or with pip:
56
57$ pip3 install nose mock
58
59Before contributing code, please read README.contributing.
60
61If you'd like to contribute translations, please see the translations section
62of http://ankisrs.net/docs/manual.html#_contributing
63
64Windows & Mac users
65---------------------
66
67The following was contributed by users in the past and will need updating
68for the latest version. It is left here in case it is any help:
69
70Windows:
71
72I have not tested the build scripts on Windows, so you'll need to solve any
73problems you encounter on your own. The easiest way is to use a source
74tarball instead of git, as that way you don't need to build the UI yourself.
75
76If you do want to use git, two alternatives have been contributed by users. As
77these are not official solutions, I'm afraid we can not provide you with any
78support for these.
79
80A powershell script:
81
82https://gist.github.com/vermiceli/108fec65759d19645ee3
83
84Or a way with git bash and perl:
85
86 1) Install "git bash".
87 2) In the tools directory, modify build_ui.sh. Locate the line that reads
88 "pyuic5 --from-imports $i -o $py.tmp" and alter it to be of the following form:
89 "<python-path-string>" "<pyuic-path-string>" $i -o $py
90 These two paths must point to your python executable, and to pyuic.py, on your
91 system. Typical paths would be:
92 <python-path> = C:\\Python27\\python.exe
93 <pyuic-path-string> = C:\\Python27\\Lib\\site-packages\\PyQt4\\uic\\pyuic.py
94
95Mac:
96
97These instructions may be incomplete as prerequisites may have already been
98installed. Most likely you will need to have installed xcode
99(https://developer.apple.com/xcode/)
100
101Install homebrew (http://brew.sh/) and then install Anki prerequisites:
102
103$ brew install python mplayer lame portaudio
104
105Now you can follow the development commands at the start of this document.
106
){kind=link}