Mercurial > kallithea
annotate docs/contributing.rst @ 7144:bfb1ae42bcbb
vcs: fix get_changesets filtering on hg repo to AND the criteria instead of OR
Mercurial scmutil.revrange takes a list of filters ... and OR them.
But when for example a user uses the api and sets branch name and date, he would
expect to only get revisions from the provided branch.
So we need to use AND when filtering.
When using AND, the special handling of start_date and end_date is no longer necessary.
Also add a test to check for this use case.
author | domruf <dominikruf@gmail.com> |
---|---|
date | Sat, 20 Jan 2018 02:24:38 +0100 |
parents | 1969f7dfb6b0 |
children | 451b3f9d814e |
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 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
18 For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
19 issue tracker is for tracking bugs, not for support, discussion, or ideas -- |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
20 please use the `mailing list`_ or :ref:`IRC <readme>` to reach the community. |
4902 | 21 |
22 We use Weblate_ to translate the user interface messages into languages other | |
23 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
|
24 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
|
25 for more details. |
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
26 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
27 |
4902 | 28 Getting started |
29 --------------- | |
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
811
diff
changeset
|
30 |
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
31 To get started with Kallithea development:: |
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
32 |
4902 | 33 hg clone https://kallithea-scm.org/repos/kallithea |
34 cd kallithea | |
35 virtualenv ../kallithea-venv | |
36 source ../kallithea-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
|
37 pip install --upgrade pip setuptools |
6748
29e9cb56f26f
docs: recommend --upgrade for all pip installations in a virtualenv
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6737
diff
changeset
|
38 pip install --upgrade -e . |
29e9cb56f26f
docs: recommend --upgrade for all pip installations in a virtualenv
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6737
diff
changeset
|
39 pip install --upgrade -r dev_requirements.txt |
7099
1969f7dfb6b0
move package.json to root directory
domruf <dominikruf@gmail.com>
parents:
7055
diff
changeset
|
40 npm install # install dependencies - both tools and data |
1969f7dfb6b0
move package.json to root directory
domruf <dominikruf@gmail.com>
parents:
7055
diff
changeset
|
41 npm run less # for generating css from less |
6555
213085032127
gearbox: make a make-config sub-command available again
Mads Kiilerich <madski@unity3d.com>
parents:
6554
diff
changeset
|
42 gearbox make-config my.ini |
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
|
43 gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp |
2c3d30095d5e
gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents:
6335
diff
changeset
|
44 gearbox serve -c my.ini --reload & |
4902 | 45 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
|
46 |
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
47 If you plan to use Bitbucket_ for sending contributions, you can also fork |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
48 Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
49 then replace the clone step above by a clone of your fork. In this case, please |
6749
84d8cff41282
docs: fix broken references
Andrew Shadura <andrew@shadura.me>
parents:
6748
diff
changeset
|
50 see :ref:`contributing-guidelines` below for configuring your fork correctly. |
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
51 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
52 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
53 Contribution flow |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
54 ----------------- |
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 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
|
57 latest upstream changes:: |
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 hg pull |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
60 hg update |
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 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
|
63 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
64 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
|
65 Guide`_ on the Mercurial wiki. |
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 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
|
68 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
|
69 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
70 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
|
71 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
|
72 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
73 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
|
74 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
75 ./scripts/run-all-cleanup |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
76 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
77 When you are completely ready, you can send your changes to the community for |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
78 review and inclusion. Most commonly used methods are sending patches to the |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
79 mailing list (via ``hg email``) or by creating a pull request on Bitbucket_. |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
80 |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
81 .. _contributing-tests: |
4902 | 82 |
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
83 |
4902 | 84 Running tests |
85 ------------- | |
86 | |
6736
1daec1628e0b
docs/contributing: move installation of dev_requirements to default instructions
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6735
diff
changeset
|
87 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
|
88 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
|
89 |
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
90 py.test |
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
91 |
6026
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
92 Note that testing on Python 2.6 also requires ``unittest2``. |
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
93 |
6629
3af2dea756db
test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents:
6571
diff
changeset
|
94 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
|
95 ``$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
|
96 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
|
97 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
|
98 |
5959
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
99 You can also use ``tox`` to run the tests with all supported Python versions |
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
100 (currently Python 2.6--2.7). |
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
101 |
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
102 When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the |
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
103 SQLite database specified there. |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
104 |
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
105 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
|
106 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
|
107 |
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
|
108 gearbox serve -c kallithea/tests/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
|
109 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
|
110 kill -9 $(cat test.pid) |
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
111 |
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
112 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
|
113 |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
114 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
|
115 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
|
116 |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
117 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
|
118 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
|
119 are:: |
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
120 |
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
121 -k EXPRESSION only run tests which match the given substring |
5835 | 122 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
|
123 expression where all names are substring-matched |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
124 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
|
125 -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
|
126 --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
|
127 all if none failed) |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
128 --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
|
129 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
|
130 setup/teardown |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
131 --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
|
132 -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
|
133 printed immediately) |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
134 |
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
|
135 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
|
136 ^^^^^^^^^^^^^^^^^ |
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
|
137 |
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
|
138 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
|
139 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
|
140 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
|
141 |
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
|
142 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
|
143 |
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
|
144 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
|
145 |
6729
043621a79cdb
docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6727
diff
changeset
|
146 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
|
147 --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
|
148 |
043621a79cdb
docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6727
diff
changeset
|
149 .. _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
|
150 |
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
151 .. _contributing-guidelines: |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
152 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
153 |
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
154 Contribution guidelines |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
155 ----------------------- |
4902 | 156 |
157 Kallithea is GPLv3 and we assume all contributions are made by the | |
158 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
159 lot about preservation of copyright and license information for existing code | |
160 that is brought into the project. | |
161 | |
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
162 Contributions will be accepted in most formats -- such as pull requests on |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
163 Bitbucket, something hosted on your own Kallithea instance, or patches sent by |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
164 email to the `kallithea-general`_ mailing list. |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
165 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
166 When contributing via Bitbucket, please make your fork of |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
167 https://bitbucket.org/conservancy/kallithea/ `non-publishing`_ -- it is one of |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
168 the settings on "Repository details" page. This ensures your commits are in |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
169 "draft" phase and makes it easier for you to address feedback and for project |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
170 maintainers to integrate your changes. |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
171 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
172 .. _non-publishing: https://www.mercurial-scm.org/wiki/Phases#Publishing_Repository |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
173 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
174 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
|
175 before posting. |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
176 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
177 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
|
178 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
|
179 "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
|
180 changes when we apply them. |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
181 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
182 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
|
183 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
|
184 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
|
185 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
|
186 be handled more casually. |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
187 |
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
|
188 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
|
189 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
|
190 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
|
191 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
|
192 ready. |
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
193 |
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
194 .. _coding-guidelines: |
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
195 |
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
196 |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
197 Coding guidelines |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
198 ----------------- |
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
199 |
4902 | 200 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
|
201 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
|
202 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
|
203 committing to ensure some basic code formatting consistency. |
4902 | 204 |
205 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
206 about Python 3 compatibility. | |
207 | |
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
208 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
|
209 to the extent it is feasible, IE8 is not. |
4902 | 210 |
211 We primarily support Linux and OS X on the server side but Windows should also work. | |
212 | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
213 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
4902 | 214 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
|
215 semantic markup with element classes and IDs that can be used for styling and testing. |
4902 | 216 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
|
217 ``display: none``). |
4902 | 218 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
219 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
|
220 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
|
221 ``{}``. |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
222 Variables holding jQuery objects should be named with a leading ``$``. |
4902 | 223 |
224 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
|
225 bug fixes, put ``(Issue #123)`` at the end of this line. |
4902 | 226 |
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
227 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
|
228 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
|
229 |
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
230 .. _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
|
231 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
232 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
|
233 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
|
234 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
|
235 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
|
236 |
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
237 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
|
238 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
4902 | 239 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
240 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
|
241 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
|
242 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
|
243 current session for the active thread. Many database operations are methods on |
2db16cda05ba
docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents:
6629
diff
changeset
|
244 such session instances - only ``Session.remove()`` should be called directly on |
2db16cda05ba
docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents:
6629
diff
changeset
|
245 the 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
|
246 |
2db16cda05ba
docs: clarify that Session usually should be called - methods should not be used directly
Mads Kiilerich <mads@kiilerich.com>
parents:
6629
diff
changeset
|
247 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
|
248 (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
|
249 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
|
250 (but also means that they cannot be shared across requests). |
4902 | 251 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
252 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
|
253 rarely needed: |
4902 | 254 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
255 * 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
|
256 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
|
257 |
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
258 * 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
|
259 ``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
|
260 been added to the session, and should not be added again. |
4902 | 261 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
262 * 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
|
263 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
|
264 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
|
265 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
|
266 objects it knows about and syncs them to the database. |
1123 | 267 |
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
268 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
|
269 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
|
270 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
|
271 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
|
272 be ``None``). |
1123 | 273 |
6571
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
274 TurboGears2 DebugBar |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
275 ^^^^^^^^^^^^^^^^^^^^ |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
276 |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
277 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
|
278 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
|
279 |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
280 * 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
|
281 * 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
|
282 variables |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
283 * 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
|
284 |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
285 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
|
286 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
|
287 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
|
288 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
|
289 |
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
290 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
|
291 ``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
|
292 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
293 |
4902 | 294 "Roadmap" |
295 --------- | |
296 | |
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
297 We do not have a road map but are waiting for your contributions. Refer to the |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
298 wiki_ for some ideas of places we might want to go -- contributions in these |
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
299 areas are very welcome. |
4902 | 300 |
301 | |
302 Thank you for your contribution! | |
303 -------------------------------- | |
304 | |
305 | |
306 .. _Weblate: http://weblate.org/ | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
307 .. _issue tracking: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
308 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
1123 | 309 .. _bitbucket: http://bitbucket.org/ |
4902 | 310 .. _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
|
311 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
4902 | 312 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/ |
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
313 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |
6571
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
314 .. _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
|
315 .. _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
|
316 .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides |