Mercurial > kallithea

annotate docs/contributing.rst @ 8914:5f4a108eed54 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
setup: support Pytest 6.2 for Python 3.10 support https://github.com/pytest-dev/pytest/issues/8539
author Mads Kiilerich <mads@kiilerich.com>
date Tue, 28 Sep 2021 14:25:03 +0200
parents 4f0de9468da3
children 0a9ddb8cd8c1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
1 .. _contributing:
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
2
2095
Marcin Kuzminski <marcin@python-works.com>
parents: 2094
diff changeset
3 =========================
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
4 Contributing to Kallithea
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
5 =========================
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
6
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
7 Kallithea is developed and maintained by its users. Please join us and scratch
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
8 your own itch.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
9
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
10
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
11 Infrastructure
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
12 --------------
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
13
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
14 The main repository is hosted on Our Own Kallithea (aka OOK) at
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
15 https://kallithea-scm.org/repos/kallithea/, our self-hosted instance
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
16 of Kallithea.
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 811
diff changeset
17
8493
5a3417b6fcf2 docs/readme: remove more references to Bitbucket
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8371
diff changeset
18 Please use the `mailing list`_ to send patches or report issues.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
19
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
20 We use Weblate_ to translate the user interface messages into languages other
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
21 than English. Join our project on `Hosted Weblate`_ to help us.
4960
f4857279cb29 docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents: 4955
diff changeset
22 To register, you can use your Bitbucket or GitHub account. See :ref:`translations`
f4857279cb29 docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents: 4955
diff changeset
23 for more details.
3993
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
24
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5432
diff changeset
25
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
26 Getting started
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
27 ---------------
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 811
diff changeset
28
8608
fc54d9d65006 docs: clarify that the virtualenv activation assume bash
Mads Kiilerich <mads@kiilerich.com>
parents: 8594
diff changeset
29 To get started with Kallithea development run the following commands in your
fc54d9d65006 docs: clarify that the virtualenv activation assume bash
Mads Kiilerich <mads@kiilerich.com>
parents: 8594
diff changeset
30 bash shell::
2032
950110f3f99f merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
31
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
32 hg clone https://kallithea-scm.org/repos/kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
33 cd kallithea
8634
6bab917402b4 docs: when using venv with a clone, recommend using 'venv' as location
Mads Kiilerich <mads@kiilerich.com>
parents: 8609
diff changeset
34 python3 -m venv venv
6bab917402b4 docs: when using venv with a clone, recommend using 'venv' as location
Mads Kiilerich <mads@kiilerich.com>
parents: 8609
diff changeset
35 . venv/bin/activate
5519
8c234ae2c258 docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents: 5502
diff changeset
36 pip install --upgrade pip setuptools
7842
3a3d96dbd445 docs: clean up installation of optional dependencies
Mads Kiilerich <mads@kiilerich.com>
parents: 7841
diff changeset
37 pip install --upgrade -e . -r dev_requirements.txt python-ldap python-pam
7406
7784a1212471 cli: convert 'gearbox make-config' into 'kallithea-cli config-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7390
diff changeset
38 kallithea-cli config-create my.ini
7414
3158cf0dafb7 cli: convert 'gearbox setup-db' into 'kallithea-cli db-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7406
diff changeset
39 kallithea-cli db-create -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7414
diff changeset
40 kallithea-cli front-end-build
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6335
diff changeset
41 gearbox serve -c my.ini --reload &
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
42 firefox http://127.0.0.1:5000/
2032
950110f3f99f merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
43
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
44
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
45 Contribution flow
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
46 -----------------
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
47
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
48 Starting from an existing Kallithea clone, make sure it is up to date with the
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
49 latest upstream changes::
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
50
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
51 hg pull
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
52 hg update
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
53
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
54 Review the :ref:`contributing-guidelines` and :ref:`coding-guidelines`.
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
55
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
56 If you are new to Mercurial, refer to Mercurial `Quick Start`_ and `Beginners
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
57 Guide`_ on the Mercurial wiki.
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
58
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
59 Now, make some changes and test them (see :ref:`contributing-tests`). Don't
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
60 forget to add new tests to cover new functionality or bug fixes.
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
61
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
62 For documentation changes, run ``make html`` from the ``docs`` directory to
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
63 generate the HTML result, then review them in your browser.
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
64
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
65 Before submitting any changes, run the cleanup script::
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
66
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
67 ./scripts/run-all-cleanup
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
68
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
69 When you are completely ready, you can send your changes to the community for
8493
5a3417b6fcf2 docs/readme: remove more references to Bitbucket
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8371
diff changeset
70 review and inclusion, via the mailing list (via ``hg email``).
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
71
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
72 .. _contributing-tests:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
73
2032
950110f3f99f merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
74
8772
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
75 Internal dependencies
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
76 ---------------------
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
77
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
78 We try to keep the code base clean and modular and avoid circular dependencies.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
79 Code should only invoke code in layers below itself.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
80
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
81 Imports should import whole modules ``from`` their parent module, perhaps
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
82 ``as`` a shortened name. Avoid imports ``from`` modules.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
83
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
84 To avoid cycles and partially initialized modules, ``__init__.py`` should *not*
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
85 contain any non-trivial imports. The top level of a module should *not* be a
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
86 facade for the module functionality.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
87
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
88 Common code for a module is often in ``base.py``.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
89
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
90 The important part of the dependency graph is approximately linear. In the
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
91 following list, modules may only depend on modules below them:
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
92
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
93 ``tests``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
94 Just get the job done - anything goes.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
95
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
96 ``bin/`` & ``config/`` & ``alembic/``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
97 The main entry points, defined in ``setup.py``. Note: The TurboGears template
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
98 use ``config`` for the high WSGI application - this is not for low level
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
99 configuration.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
100
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
101 ``controllers/``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
102 The top level web application, with TurboGears using the ``root`` controller
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
103 as entry point, and ``routing`` dispatching to other controllers.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
104
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
105 ``templates/**.html``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
106 The "view", rendering to HTML. Invoked by controllers which can pass them
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
107 anything from lower layers - especially ``helpers`` available as ``h`` will
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
108 cut through all layers, and ``c`` gives access to global variables.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
109
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
110 ``lib/helpers.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
111 High level helpers, exposing everything to templates as ``h``. It depends on
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
112 everything and has a huge dependency chain, so it should not be used for
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
113 anything else. TODO.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
114
8809
4f0de9468da3 controllers: move controllers base class from lib/base to controllers
Mads Kiilerich <mads@kiilerich.com>
parents: 8772
diff changeset
115 ``controllers/base.py``
8772
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
116 The base class of controllers, with lots of model knowledge.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
117
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
118 ``lib/auth.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
119 All things related to authentication. TODO.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
120
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
121 ``lib/utils.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
122 High level utils with lots of model knowledge. TODO.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
123
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
124 ``lib/hooks.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
125 Hooks into "everything" to give centralized logging to database, cache
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
126 invalidation, and extension handling. TODO.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
127
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
128 ``model/``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
129 Convenience business logic wrappers around database models.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
130
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
131 ``model/db.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
132 Defines the database schema and provides some additional logic.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
133
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
134 ``model/scm.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
135 All things related to anything. TODO.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
136
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
137 SQLAlchemy
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
138 Database session and transaction in thread-local variables.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
139
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
140 ``lib/utils2.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
141 Low level utils specific to Kallithea.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
142
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
143 ``lib/webutils.py``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
144 Low level generic utils with awareness of the TurboGears environment.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
145
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
146 TurboGears
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
147 Request, response and state like i18n gettext in thread-local variables.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
148 External dependency with global state - usage should be minimized.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
149
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
150 ``lib/vcs/``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
151 Previously an independent library. No awareness of web, database, or state.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
152
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
153 ``lib/*``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
154 Various "pure" functionality not depending on anything else.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
155
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
156 ``__init__``
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
157 Very basic Kallithea constants - some of them are set very early based on ``.ini``.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
158
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
159 This is not exactly how it is right now, but we aim for something like that.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
160 Especially the areas marked as TODO have some problems that need untangling.
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
161
52816813cbec docs: describe, visualize, and verify internal code structure and layering
Mads Kiilerich <mads@kiilerich.com>
parents: 8657
diff changeset
162
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
163 Running tests
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
164 -------------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
165
6736
1daec1628e0b docs/contributing: move installation of dev_requirements to default instructions
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6735
diff changeset
166 After finishing your changes make sure all tests pass cleanly. Run the testsuite
1daec1628e0b docs/contributing: move installation of dev_requirements to default instructions
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6735
diff changeset
167 by invoking ``py.test`` from the project root::
5959
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
168
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
169 py.test
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
170
6629
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
171 Note that on unix systems, the temporary directory (``/tmp`` or where
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
172 ``$TMPDIR`` points) must allow executable files; Git hooks must be executable,
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
173 and the test suite creates repositories in the temporary directory. Linux
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
174 systems with /tmp mounted noexec will thus fail.
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
175
8593
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
176 Tests can be run on PostgreSQL like::
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
177
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
178 sudo -u postgres createuser 'kallithea-test' --pwprompt # password password
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
179 sudo -u postgres createdb 'kallithea-test' --owner 'kallithea-test'
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
180 REUSE_TEST_DB='postgresql://kallithea-test:password@localhost/kallithea-test' py.test
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
181
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
182 Tests can be run on MariaDB/MySQL like::
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
183
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
184 echo "GRANT ALL PRIVILEGES ON \`kallithea-test\`.* TO 'kallithea-test'@'localhost' IDENTIFIED BY 'password'" | sudo -u mysql mysql
8594
3c503044e9f1 mysql: bump sqlalchemy.url MariaDB/MySQL charset to to 'utf8mb4' to get full UTF-8 support
Mads Kiilerich <mads@kiilerich.com>
parents: 8593
diff changeset
185 TEST_DB='mysql://kallithea-test:password@localhost/kallithea-test?charset=utf8mb4' py.test
8593
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB
Mads Kiilerich <mads@kiilerich.com>
parents: 8371
diff changeset
186
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
187 You can also use ``tox`` to run the tests with all supported Python versions.
3993
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
188
7390
451b3f9d814e docs: update i18n doc after TG migration changed lang to i18n.lang and test.ini is generated
Mads Kiilerich <mads@kiilerich.com>
parents: 7099
diff changeset
189 When running tests, Kallithea generates a `test.ini` based on template values
451b3f9d814e docs: update i18n doc after TG migration changed lang to i18n.lang and test.ini is generated
Mads Kiilerich <mads@kiilerich.com>
parents: 7099
diff changeset
190 in `kallithea/tests/conftest.py` and populates the SQLite database specified
451b3f9d814e docs: update i18n doc after TG migration changed lang to i18n.lang and test.ini is generated
Mads Kiilerich <mads@kiilerich.com>
parents: 7099
diff changeset
191 there.
4920
329dd2b2025d docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
192
329dd2b2025d docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
193 It is possible to avoid recreating the full test database on each invocation of
329dd2b2025d docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
194 the tests, thus eliminating the initial delay. To achieve this, run the tests as::
3993
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
195
7390
451b3f9d814e docs: update i18n doc after TG migration changed lang to i18n.lang and test.ini is generated
Mads Kiilerich <mads@kiilerich.com>
parents: 7099
diff changeset
196 gearbox serve -c /tmp/kallithea-test-XXX/test.ini --pid-file=test.pid --daemon
5701
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
197 KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 py.test
3993
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
198 kill -9 $(cat test.pid)
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
199
5701
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
200 In these commands, the following variables are used::
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
201
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
202 KALLITHEA_WHOOSH_TEST_DISABLE=1 - skip whoosh index building and tests
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
203 KALLITHEA_NO_TMP_PATH=1 - disable new temp path for tests, used mostly for testing_vcs_operations
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
204
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
205 You can run individual tests by specifying their path as argument to py.test.
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
206 py.test also has many more options, see `py.test -h`. Some useful options
4927
f879e7ea1c4b docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4926
diff changeset
207 are::
f879e7ea1c4b docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4926
diff changeset
208
5701
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
209 -k EXPRESSION only run tests which match the given substring
5835
e45f5dbc2533 spelling: evaluable
timeless@gmail.com
parents: 5758
diff changeset
210 expression. An expression is a python evaluable
5701
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
211 expression where all names are substring-matched
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
212 against test names and their parent classes. Example:
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
213 -x, --exitfirst exit instantly on first error or failed test.
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
214 --lf rerun only the tests that failed at the last run (or
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
215 all if none failed)
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
216 --ff run all tests but run the last failures first. This
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
217 may re-order tests and thus lead to repeated fixture
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
218 setup/teardown
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
219 --pdb start the interactive Python debugger on errors.
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
220 -s, --capture=no don't capture stdout (any stdout output will be
2d2decce586f pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 5519
diff changeset
221 printed immediately)
4920
329dd2b2025d docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 4914
diff changeset
222
6727
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
223 Performance tests
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
224 ^^^^^^^^^^^^^^^^^
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
225
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
226 A number of performance tests are present in the test suite, but they are
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
227 not run in a standard test run. These tests are useful to
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
228 evaluate the impact of certain code changes with respect to performance.
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
229
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
230 To run these tests::
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
231
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
232 env TEST_PERFORMANCE=1 py.test kallithea/tests/performance
813e1f9d9c53 tests: add simple (skipped) unit tests for graph_data that may be used to measure performance
Eivind Tagseth <eivindt@gmail.com>
parents: 6639
diff changeset
233
6729
043621a79cdb docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6727
diff changeset
234 To analyze performance, you could install pytest-profiling_, which enables the
043621a79cdb docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6727
diff changeset
235 --profile and --profile-svg options to py.test.
043621a79cdb docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6727
diff changeset
236
043621a79cdb docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6727
diff changeset
237 .. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling
043621a79cdb docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6727
diff changeset
238
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
239 .. _contributing-guidelines:
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
240
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5432
diff changeset
241
6314
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
242 Contribution guidelines
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
243 -----------------------
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
244
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
245 Kallithea is GPLv3 and we assume all contributions are made by the
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
246 committer/contributor and under GPLv3 unless explicitly stated. We do care a
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
247 lot about preservation of copyright and license information for existing code
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
248 that is brought into the project.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
249
8657
26fcb8c16c2c docs/contributing: wrap long line
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8643
diff changeset
250 Contributions will be accepted in most formats -- such as commits hosted on your
26fcb8c16c2c docs/contributing: wrap long line
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8643
diff changeset
251 own Kallithea instance, or patches sent by email to the `kallithea-general`_
26fcb8c16c2c docs/contributing: wrap long line
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 8643
diff changeset
252 mailing list.
6314
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
253
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
254 Make sure to test your changes both manually and with the automatic tests
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
255 before posting.
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
256
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
257 We care about quality and review and keeping a clean repository history. We
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
258 might give feedback that requests polishing contributions until they are
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
259 "perfect". We might also rebase and collapse and make minor adjustments to your
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
260 changes when we apply them.
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
261
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
262 We try to make sure we have consensus on the direction the project is taking.
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
263 Everything non-sensitive should be discussed in public -- preferably on the
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
264 mailing list. We aim at having all non-trivial changes reviewed by at least
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
265 one other core developer before pushing. Obvious non-controversial changes will
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
266 be handled more casually.
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
267
6737
a755bacaa725 docs/contributing: clarify that Kallithea now also has a stable branch
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6736
diff changeset
268 There is a main development branch ("default") which is generally stable so that
a755bacaa725 docs/contributing: clarify that Kallithea now also has a stable branch
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6736
diff changeset
269 it can be (and is) used in production. There is also a "stable" branch that is
a755bacaa725 docs/contributing: clarify that Kallithea now also has a stable branch
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6736
diff changeset
270 almost exclusively reserved for bug fixes or trivial changes. Experimental
a755bacaa725 docs/contributing: clarify that Kallithea now also has a stable branch
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6736
diff changeset
271 changes should live elsewhere (for example in a pull request) until they are
a755bacaa725 docs/contributing: clarify that Kallithea now also has a stable branch
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6736
diff changeset
272 ready.
6314
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
273
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
274 .. _coding-guidelines:
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
275
6314
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
276
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
277 Coding guidelines
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
278 -----------------
50f1a6adbefd docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents: 6026
diff changeset
279
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
280 We don't have a formal coding/formatting standard. We are currently using a mix
6334
cc21a2b86a30 docs: update links to Mercurial's website and wiki
Anton Shestakov <av6@dwimlabs.net>
parents: 5755
diff changeset
281 of Mercurial's (https://www.mercurial-scm.org/wiki/CodingStyle), pep8, and
5971
a5a16aad6b3e docs: run-all-cleanup superseded whitespaceleanup.sh
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5960
diff changeset
282 consistency with existing code. Run ``scripts/run-all-cleanup`` before
a5a16aad6b3e docs: run-all-cleanup superseded whitespaceleanup.sh
Konstantin Veretennicov <kveretennicov@gmail.com>
parents: 5960
diff changeset
283 committing to ensure some basic code formatting consistency.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
284
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
285 We support Python 3.6 and later.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
286
5308
b8d716694dc8 js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents: 4960
diff changeset
287 We try to support the most common modern web browsers. IE9 is still supported
b8d716694dc8 js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents: 4960
diff changeset
288 to the extent it is feasible, IE8 is not.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
289
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
290 We primarily support Linux and OS X on the server side but Windows should also work.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
291
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
292 HTML templates should use 2 spaces for indentation ... but be pragmatic. We
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
293 should use templates cleverly and avoid duplication. We should use reasonable
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
294 semantic markup with element classes and IDs that can be used for styling and testing.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
295 We should only use inline styles in places where it really is semantic (such as
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
296 ``display: none``).
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
297
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
298 JavaScript must use ``;`` between/after statements. Indentation 4 spaces. Inline
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
299 multiline functions should be indented two levels -- one for the ``()`` and one for
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
300 ``{}``.
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
301 Variables holding jQuery objects should be named with a leading ``$``.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
302
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
303 Commit messages should have a leading short line summarizing the changes. For
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
304 bug fixes, put ``(Issue #123)`` at the end of this line.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
305
5432
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
306 Use American English grammar and spelling overall. Use `English title case`_ for
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
307 page titles, button labels, headers, and 'labels' for fields in forms.
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
308
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
309 .. _English title case: https://en.wikipedia.org/wiki/Capitalization#Title_case
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents: 5425
diff changeset
310
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
311 Template helpers (that is, everything in ``kallithea.lib.helpers``)
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
312 should only be referenced from templates. If you need to call a
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
313 helper from the Python code, consider moving the function somewhere
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
314 else (e.g. to the model).
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
316 Notes on the SQLAlchemy session
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
317 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
318
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
319 Each HTTP request runs inside an independent SQLAlchemy session (as well
6639
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents: 6629
diff changeset
320 as in an independent database transaction). ``Session`` is the session manager
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents: 6629
diff changeset
321 and factory. ``Session()`` will create a new session on-demand or return the
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents: 6629
diff changeset
322 current session for the active thread. Many database operations are methods on
8323
2b8892f92b46 docs: fix contributing.rst reference to Session.remove()
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
323 such session instances. The session will generally be removed by
2b8892f92b46 docs: fix contributing.rst reference to Session.remove()
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
324 TurboGears automatically.
6639
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents: 6629
diff changeset
325
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents: 6629
diff changeset
326 Database model objects
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
327 (almost) always belong to a particular SQLAlchemy session, which means
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
328 that SQLAlchemy will ensure that they're kept in sync with the database
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
329 (but also means that they cannot be shared across requests).
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
330
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
331 Objects can be added to the session using ``Session().add``, but this is
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
332 rarely needed:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
333
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
334 * When creating a database object by calling the constructor directly,
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
335 it must explicitly be added to the session.
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
336
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
337 * When creating an object using a factory function (like
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
338 ``create_repo``), the returned object has already (by convention)
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
339 been added to the session, and should not be added again.
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
340
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
341 * When getting an object from the session (via ``Session().query`` or
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
342 any of the utility functions that look up objects in the database),
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
343 it's already part of the session, and should not be added again.
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
344 SQLAlchemy monitors attribute modifications automatically for all
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
345 objects it knows about and syncs them to the database.
1123
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
346
6315
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
347 SQLAlchemy also flushes changes to the database automatically; manually
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
348 calling ``Session().flush`` is usually only necessary when the Python
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
349 code needs the database to assign an "auto-increment" primary key ID to
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
350 a freshly created model object (before flushing, the ID attribute will
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents: 6314
diff changeset
351 be ``None``).
1123
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
352
8358
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
353 Debugging
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
354 ^^^^^^^^^
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
355
8371
3b1c53643b09 doc: fix wording of debug hint in contributing.rst
Mads Kiilerich <mads@kiilerich.com>
parents: 8358
diff changeset
356 A good way to trace what Kallithea is doing is to keep an eye on the output on
3b1c53643b09 doc: fix wording of debug hint in contributing.rst
Mads Kiilerich <mads@kiilerich.com>
parents: 8358
diff changeset
357 stdout/stderr of the server process. Perhaps change ``my.ini`` to log at
8358
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
358 ``DEBUG`` or ``INFO`` level, especially ``[logger_kallithea]``, but perhaps
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
359 also other loggers. It is often easier to add additional ``log`` or ``print``
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
360 statements than to use a Python debugger.
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
361
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
362 Sometimes it is simpler to disable ``errorpage.enabled`` and perhaps also
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
363 ``trace_errors.enable`` to expose raw errors instead of adding extra
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
364 processing. Enabling ``debug`` can be helpful for showing and exploring
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
365 tracebacks in the browser, but is also insecure and will add extra processing.
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors
Mads Kiilerich <mads@kiilerich.com>
parents: 8323
diff changeset
366
6571
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
367 TurboGears2 DebugBar
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
368 ^^^^^^^^^^^^^^^^^^^^
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
369
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
370 It is possible to enable the TurboGears2-provided DebugBar_, a toolbar overlayed
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
371 over the Kallithea web interface, allowing you to see:
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
372
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
373 * timing information of the current request, including profiling information
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
374 * request data, including GET data, POST data, cookies, headers and environment
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
375 variables
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
376 * a list of executed database queries, including timing and result values
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
377
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
378 DebugBar is only activated when ``debug = true`` is set in the configuration
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
379 file. This is important, because the DebugBar toolbar will be visible for all
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
380 users, and allow them to see information they should not be allowed to see. Like
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
381 is anyway the case for ``debug = true``, do not use this in production!
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
382
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
383 To enable DebugBar, install ``tgext.debugbar`` and ``kajiki`` (typically via
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
384 ``pip``) and restart Kallithea (in debug mode).
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
385
5433
fbbe80e3322b docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents: 5432
diff changeset
386
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
387 Thank you for your contribution!
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
388 --------------------------------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
389
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
390
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
391 .. _Weblate: http://weblate.org/
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
392 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
393 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
394 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/
6571
908e186abd8d backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6555
diff changeset
395 .. _DebugBar: https://github.com/TurboGears/tgext.debugbar
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
396 .. _Quick Start: https://www.mercurial-scm.org/wiki/QuickStart
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
397 .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides