Mercurial > kallithea
annotate docs/contributing.rst @ 8086:488b52cad890 stable
logging: always invoke fileConfig with '__file__' and 'here'
WSGI servers tend to provide '__file__' and 'here' as 'defaults' when invoking
fileConfig, so '%(here)s' string interpolation also can be used in logging
configuration.
Make sure we do the same when we initialize logging without using a WSGI server.
It is annoying to have to do this, and it will only in rare cases make any
difference ... but it seems like the best option.
Patch also modified by Mads Kiilerich.
| author | Wolfgang Scherer <Wolfgang.Scherer@gmx.de> |
|---|---|
| date | Sun, 29 Dec 2019 17:35:13 +0100 |
| parents | 3a3d96dbd445 |
| children | 89e9aef9b983 |
| 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 |
|
7842
3a3d96dbd445
docs: clean up installation of optional dependencies
Mads Kiilerich <mads@kiilerich.com>
parents:
7841
diff
changeset
|
38 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
|
39 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
|
40 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
|
41 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
|
42 gearbox serve -c my.ini --reload & |
| 4902 | 43 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
|
44 |
|
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
45 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
|
46 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
|
47 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
|
48 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
|
49 |
|
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 Contribution flow |
|
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 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
54 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
|
55 latest upstream changes:: |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
56 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
57 hg pull |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
58 hg update |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
59 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
60 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
|
61 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
62 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
|
63 Guide`_ on the Mercurial wiki. |
|
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 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
|
66 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
|
67 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
68 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
|
69 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
|
70 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
71 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
|
72 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
73 ./scripts/run-all-cleanup |
|
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 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
|
76 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
|
77 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
|
78 |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
79 .. _contributing-tests: |
| 4902 | 80 |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
81 |
| 4902 | 82 Running tests |
| 83 ------------- | |
| 84 | |
|
6736
1daec1628e0b
docs/contributing: move installation of dev_requirements to default instructions
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6735
diff
changeset
|
85 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
|
86 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
|
87 |
|
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
88 py.test |
|
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
89 |
|
6629
3af2dea756db
test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents:
6571
diff
changeset
|
90 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
|
91 ``$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
|
92 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
|
93 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
|
94 |
|
5959
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
95 You can also use ``tox`` to run the tests with all supported Python versions |
|
7708
ab30729c735c
setup: drop support for Python 2.6
Mads Kiilerich <mads@kiilerich.com>
parents:
7626
diff
changeset
|
96 (currently only Python 2.7). |
|
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
97 |
|
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
|
98 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
|
99 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
|
100 there. |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
101 |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
102 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
|
103 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
|
104 |
|
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
|
105 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
|
106 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
|
107 kill -9 $(cat test.pid) |
|
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
108 |
|
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
109 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
|
110 |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
111 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
|
112 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
|
113 |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
114 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
|
115 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
|
116 are:: |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
117 |
|
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
118 -k EXPRESSION only run tests which match the given substring |
| 5835 | 119 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
|
120 expression where all names are substring-matched |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
121 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
|
122 -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
|
123 --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
|
124 all if none failed) |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
125 --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
|
126 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
|
127 setup/teardown |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
128 --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
|
129 -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
|
130 printed immediately) |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
131 |
|
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
|
132 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
|
133 ^^^^^^^^^^^^^^^^^ |
|
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
|
134 |
|
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 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
|
136 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
|
137 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
|
138 |
|
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 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
|
140 |
|
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 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
|
142 |
|
6729
043621a79cdb
docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6727
diff
changeset
|
143 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
|
144 --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
|
145 |
|
043621a79cdb
docs: mention pytest-profiling
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6727
diff
changeset
|
146 .. _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
|
147 |
|
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
148 .. _contributing-guidelines: |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
149 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
150 |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
151 Contribution guidelines |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
152 ----------------------- |
| 4902 | 153 |
| 154 Kallithea is GPLv3 and we assume all contributions are made by the | |
| 155 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
| 156 lot about preservation of copyright and license information for existing code | |
| 157 that is brought into the project. | |
| 158 | |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
159 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
|
160 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
|
161 email to the `kallithea-general`_ mailing list. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
162 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
163 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
|
164 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
|
165 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
|
166 "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
|
167 maintainers to integrate your changes. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
168 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
169 .. _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
|
170 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
171 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
|
172 before posting. |
|
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 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
|
175 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
|
176 "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
|
177 changes when we apply them. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
178 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
179 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
|
180 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
|
181 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
|
182 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
|
183 be handled more casually. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
184 |
|
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
|
185 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
|
186 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
|
187 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
|
188 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
|
189 ready. |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
190 |
|
6735
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
191 .. _coding-guidelines: |
|
49be3b49c8e2
docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents:
6729
diff
changeset
|
192 |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
193 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
194 Coding guidelines |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
195 ----------------- |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
196 |
| 4902 | 197 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
|
198 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
|
199 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
|
200 committing to ensure some basic code formatting consistency. |
| 4902 | 201 |
|
7708
ab30729c735c
setup: drop support for Python 2.6
Mads Kiilerich <mads@kiilerich.com>
parents:
7626
diff
changeset
|
202 We currently only support Python 2.7.x and nothing else. For now we don't care |
| 4902 | 203 about Python 3 compatibility. |
| 204 | |
|
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
205 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
|
206 to the extent it is feasible, IE8 is not. |
| 4902 | 207 |
| 208 We primarily support Linux and OS X on the server side but Windows should also work. | |
| 209 | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
210 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
| 4902 | 211 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
|
212 semantic markup with element classes and IDs that can be used for styling and testing. |
| 4902 | 213 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
|
214 ``display: none``). |
| 4902 | 215 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
216 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
|
217 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
|
218 ``{}``. |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
219 Variables holding jQuery objects should be named with a leading ``$``. |
| 4902 | 220 |
| 221 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
|
222 bug fixes, put ``(Issue #123)`` at the end of this line. |
| 4902 | 223 |
|
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
224 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
|
225 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
|
226 |
|
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
227 .. _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
|
228 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
229 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
|
230 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
|
231 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
|
232 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
|
233 |
|
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
234 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
|
235 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4902 | 236 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
237 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
|
238 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
|
239 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
|
240 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
|
241 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
|
242 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
|
243 |
|
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 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
|
245 (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
|
246 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
|
247 (but also means that they cannot be shared across requests). |
| 4902 | 248 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
249 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
|
250 rarely needed: |
| 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 * 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
|
253 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
|
254 |
|
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 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
|
256 ``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
|
257 been added to the session, and should not be added again. |
| 4902 | 258 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
259 * 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
|
260 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
|
261 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
|
262 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
|
263 objects it knows about and syncs them to the database. |
| 1123 | 264 |
|
6315
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 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
|
266 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
|
267 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
|
268 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
|
269 be ``None``). |
| 1123 | 270 |
|
6571
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
271 TurboGears2 DebugBar |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
272 ^^^^^^^^^^^^^^^^^^^^ |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
273 |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
274 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
|
275 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
|
276 |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
277 * 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
|
278 * 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
|
279 variables |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
280 * 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
|
281 |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
282 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
|
283 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
|
284 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
|
285 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
|
286 |
|
908e186abd8d
backend: add TurboGears2 DebugBar support
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
6555
diff
changeset
|
287 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
|
288 ``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
|
289 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
290 |
| 4902 | 291 "Roadmap" |
| 292 --------- | |
| 293 | |
|
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
294 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
|
295 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
|
296 areas are very welcome. |
| 4902 | 297 |
| 298 | |
| 299 Thank you for your contribution! | |
| 300 -------------------------------- | |
| 301 | |
| 302 | |
| 303 .. _Weblate: http://weblate.org/ | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
304 .. _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
|
305 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
| 1123 | 306 .. _bitbucket: http://bitbucket.org/ |
| 4902 | 307 .. _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
|
308 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
| 4902 | 309 .. _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
|
310 .. _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
|
311 .. _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
|
312 .. _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
|
313 .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides |