Mercurial > kallithea

annotate docs/contributing.rst @ 7467:2e7ffb755d4f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
front-end: use At.js for MentionsAutoComplete We want to get rid of YUI, and select2 is not well suited for this purpose. So use At.js, which is made just for this use case. Original implementation was modified by Mads Kiilerich.
author domruf <dominikruf@gmail.com>
date Mon, 10 Dec 2018 22:54:04 +0100
parents b66725ba01ed
children 19af3fef3b34
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
1 .. _contributing:
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
2
2095
Marcin Kuzminski <marcin@python-works.com>
parents: 2094
diff changeset
3 =========================
4192
e73a69cb98dc Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents: 4186
diff changeset
4 Contributing to Kallithea
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
5 =========================
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
6
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
7 Kallithea is developed and maintained by its users. Please join us and scratch
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
8 your own itch.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
9
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
10
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
11 Infrastructure
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
12 --------------
811
bb35ad076e2f docs updates
Marcin Kuzminski <marcin@python-works.com>
parents:
diff changeset
13
5425
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
14 The main repository is hosted on Our Own Kallithea (aka OOK) at
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
15 https://kallithea-scm.org/repos/kallithea/, our self-hosted instance
5ae8e644aa88 docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents: 5416
diff changeset
16 of Kallithea.
1062
053983a464e4 docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents: 811
diff changeset
17
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
21
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
22 We use Weblate_ to translate the user interface messages into languages other
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
28 Getting started
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
33 hg clone https://kallithea-scm.org/repos/kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
34 cd kallithea
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
35 virtualenv ../kallithea-venv
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
7406
7784a1212471 cli: convert 'gearbox make-config' into 'kallithea-cli config-create'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7390
diff changeset
40 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
41 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
42 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
43 gearbox serve -c my.ini --reload &
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
44 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
45
6735
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
46 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
47 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
48 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
49 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
50
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 Contribution flow
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
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
55 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
56 latest upstream changes::
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
57
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
58 hg pull
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
59 hg update
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
60
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
61 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
62
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
63 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
64 Guide`_ on the Mercurial wiki.
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
65
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
66 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
67 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
68
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
69 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
70 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
71
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
72 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
73
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
74 ./scripts/run-all-cleanup
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
75
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
76 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
77 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
78 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
79
49be3b49c8e2 docs/contributing: make contribution information more accessible
Karl Goetz <karl@kgoetz.id.au>
parents: 6729
diff changeset
80 .. _contributing-tests:
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
81
2032
950110f3f99f merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents: 1123
diff changeset
82
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
83 Running tests
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
84 -------------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
85
6736
1daec1628e0b docs/contributing: move installation of dev_requirements to default instructions
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents: 6735
diff changeset
86 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
87 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
88
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
89 py.test
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
90
6026
dd676fdeda0f setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents: 5972
diff changeset
91 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
92
6629
3af2dea756db test: add warning about not mounting /tmp noexec
domruf <dominikruf@gmail.com>
parents: 6571
diff changeset
93 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
94 ``$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
95 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
96 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
97
5959
e6fafb5ed70d docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents: 5885
diff changeset
98 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
99 (currently Python 2.6--2.7).
3993
b53cef6faf22 updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents: 3700
diff changeset
100
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
101 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
102 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
103 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
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
108 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
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
e45f5dbc2533 spelling: evaluable
timeless@gmail.com
parents: 5758
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
156
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
157 Kallithea is GPLv3 and we assume all contributions are made by the
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
158 committer/contributor and under GPLv3 unless explicitly stated. We do care a
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
159 lot about preservation of copyright and license information for existing code
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
160 that is brought into the project.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
204
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
205 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
206 about Python 3 compatibility.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
210
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
211 We primarily support Linux and OS X on the server side but Windows should also work.
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
223
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
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
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
294 "Roadmap"
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
295 ---------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
300
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
301
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
302 Thank you for your contribution!
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
303 --------------------------------
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
304
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
305
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
9472a0150bf0 docs update
Marcin Kuzminski <marcin@python-works.com>
parents: 1092
diff changeset
309 .. _bitbucket: http://bitbucket.org/
4902
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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
03bbd33bc084 docs: rework stuff
Mads Kiilerich <madski@unity3d.com>
parents: 4522
diff changeset
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