Mercurial > kallithea
annotate docs/contributing.rst @ 8836:ff58aa21f9a3
hooks: fix incorrect visual nesting in the admin UI
A form-group was missing.
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Sun, 10 Jan 2021 01:05:32 +0100 |
parents | 4f0de9468da3 |
children | 0a9ddb8cd8c1 |
rev | line source |
---|---|
811 | 1 .. _contributing: |
2 | |
2095 | 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 | 5 ========================= |
6 | |
4902 | 7 Kallithea is developed and maintained by its users. Please join us and scratch |
8 your own itch. | |
9 | |
10 | |
11 Infrastructure | |
12 -------------- | |
811 | 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 | 19 |
20 We use Weblate_ to translate the user interface messages into languages other | |
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 | 26 Getting started |
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 | 32 hg clone https://kallithea-scm.org/repos/kallithea |
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 | 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 | 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 | 163 Running tests |
164 ------------- | |
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 | 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 | 244 |
245 Kallithea is GPLv3 and we assume all contributions are made by the | |
246 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
247 lot about preservation of copyright and license information for existing code | |
248 that is brought into the project. | |
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 | 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 | 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 | 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 | 289 |
290 We primarily support Linux and OS X on the server side but Windows should also work. | |
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 | 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 | 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 | 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 | 302 |
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 387 Thank you for your contribution! |
388 -------------------------------- | |
389 | |
390 | |
391 .. _Weblate: http://weblate.org/ | |
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 | 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 |