kallithea: docs/contributing.rst annotate

annotate docs/contributing.rst @ 8594:3c503044e9f1

mysql: bump sqlalchemy.url MariaDB/MySQL charset to to 'utf8mb4' to get full UTF-8 support The change in 210e76d69b62 only changed character_set_database, as shown by output after: --- a/kallithea/model/base.py +++ b/kallithea/model/base.py @@ -46,3 +46,8 @@ def init_model(engine): engine_str = obfuscate_url_pw(str(engine.url)) log.info("initializing db for %s", engine_str) meta.Base.metadata.bind = engine + + meta.Session.configure(bind=engine) + for a, b in meta.Session().execute('''show variables''').fetchall(): + if 'character_set_' in a: + print(a, repr(b)) Before, with charset=utf8, the utf8mb3 charset was used all the way through the stack: [kallithea.model.base] initializing db for mysql://kallithea-test:XXXXX@localhost/kallithea-test?charset=utf8 character_set_client 'utf8' character_set_connection 'utf8' character_set_database 'utf8mb4' character_set_filesystem 'binary' character_set_results 'utf8' character_set_server 'latin1' character_set_system 'utf8' With explicit charset=utf8mb4: [kallithea.model.base] initializing db for mysql://kallithea-test:XXXXX@localhost/kallithea-test?charset=utf8mb4 character_set_client 'utf8mb4' character_set_connection 'utf8mb4' character_set_database 'utf8mb4' character_set_filesystem 'binary' character_set_results 'utf8mb4' character_set_server 'latin1' character_set_system 'utf8'

author	Mads Kiilerich <mads@kiilerich.com>
date	Wed, 01 Jul 2020 14:58:56 +0200
parents	922808a61274
children	fc54d9d65006

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 17c9393e9645 docs 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
8193 89e9aef9b983 py3: use "python3 -m venv" instead of virtualenv package Mads Kiilerich <mads@kiilerich.com> parents: 7842 diff changeset	35 python3 -m venv ../kallithea-venv
4902 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
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 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	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 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	80
2032 950110f3f99f merged changes from stable into beta Marcin Kuzminski <marcin@python-works.com> parents: 1123 diff changeset	81
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	82 Running tests
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	83 -------------
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	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
8593 922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	95 Tests can be run on PostgreSQL like::
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	96
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	97 sudo -u postgres createuser 'kallithea-test' --pwprompt # password password
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	98 sudo -u postgres createdb 'kallithea-test' --owner 'kallithea-test'
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	99 REUSE_TEST_DB='postgresql://kallithea-test:password@localhost/kallithea-test' py.test
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	100
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	101 Tests can be run on MariaDB/MySQL like::
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	102
922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	103 echo "GRANT ALL PRIVILEGES ON \`kallithea-test\`.* TO 'kallithea-test'@'localhost' IDENTIFIED BY 'password'" \| sudo -u mysql mysql
8594 3c503044e9f1 mysql: bump sqlalchemy.url MariaDB/MySQL charset to to 'utf8mb4' to get full UTF-8 support Mads Kiilerich <mads@kiilerich.com> parents: 8593 diff changeset	104 TEST_DB='mysql://kallithea-test:password@localhost/kallithea-test?charset=utf8mb4' py.test
8593 922808a61274 tests: introduce REUSE_TEST_DB as an alternative to TEST_DB Mads Kiilerich <mads@kiilerich.com> parents: 8371 diff changeset	105
8209 01aca0a4f876 py3: officially support Python 3 Mads Kiilerich <mads@kiilerich.com> parents: 8193 diff changeset	106 You can also use ``tox`` to run the tests with all supported Python versions.
3993 b53cef6faf22 updated contributing docs Marcin Kuzminski <marcin@python-works.com> parents: 3700 diff changeset	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 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	109 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	110 there.
4920 329dd2b2025d docs/contributing: cleanup test section Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4914 diff changeset	111
329dd2b2025d docs/contributing: cleanup test section Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4914 diff changeset	112 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	113 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	114
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	115 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	116 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	117 kill -9 $(cat test.pid)
b53cef6faf22 updated contributing docs Marcin Kuzminski <marcin@python-works.com> parents: 3700 diff changeset	118
5701 2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	119 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	120
2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	121 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	122 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	123
2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	124 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	125 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	126 are::
f879e7ea1c4b docs/contributing: explicitly mention some useful options to nosetests Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4926 diff changeset	127
5701 2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	128 -k EXPRESSION only run tests which match the given substring
5835 e45f5dbc2533 spelling: evaluable timeless@gmail.com parents: 5758 diff changeset	129 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	130 expression where all names are substring-matched
2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	131 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	132 -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	133 --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	134 all if none failed)
2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	135 --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	136 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	137 setup/teardown
2d2decce586f pytest migration: update documentation Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 5519 diff changeset	138 --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	139 -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	140 printed immediately)
4920 329dd2b2025d docs/contributing: cleanup test section Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4914 diff changeset	141
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	142 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	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
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 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	146 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	147 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	148
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	149 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	150
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	151 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	152
6729 043621a79cdb docs: mention pytest-profiling Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6727 diff changeset	153 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	154 --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	155
043621a79cdb docs: mention pytest-profiling Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6727 diff changeset	156 .. _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	157
6735 49be3b49c8e2 docs/contributing: make contribution information more accessible Karl Goetz <karl@kgoetz.id.au> parents: 6729 diff changeset	158 .. _contributing-guidelines:
49be3b49c8e2 docs/contributing: make contribution information more accessible Karl Goetz <karl@kgoetz.id.au> parents: 6729 diff changeset	159
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5432 diff changeset	160
6314 50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	161 Contribution guidelines
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	162 -----------------------
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	163
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	164 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	165 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	166 lot about preservation of copyright and license information for existing code
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	167 that is brought into the project.
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	168
6314 50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	169 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	170 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	171 email to the `kallithea-general`_ mailing list.
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	172
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	173 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	174 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	175 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	176 "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	177 maintainers to integrate your changes.
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 .. _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	180
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	181 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	182 before posting.
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	183
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	184 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	185 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	186 "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	187 changes when we apply them.
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	188
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	189 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	190 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	191 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	192 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	193 be handled more casually.
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	194
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	195 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	196 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	197 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	198 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	199 ready.
6314 50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	200
6735 49be3b49c8e2 docs/contributing: make contribution information more accessible Karl Goetz <karl@kgoetz.id.au> parents: 6729 diff changeset	201 .. _coding-guidelines:
49be3b49c8e2 docs/contributing: make contribution information more accessible Karl Goetz <karl@kgoetz.id.au> parents: 6729 diff changeset	202
6314 50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	203
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	204 Coding guidelines
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	205 -----------------
50f1a6adbefd docs: separate coding/contribution guidelines Søren Løvborg <sorenl@unity3d.com> parents: 6026 diff changeset	206
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	207 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	208 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	209 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	210 committing to ensure some basic code formatting consistency.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	211
8209 01aca0a4f876 py3: officially support Python 3 Mads Kiilerich <mads@kiilerich.com> parents: 8193 diff changeset	212 We support Python 3.6 and later.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	213
5308 b8d716694dc8 js: drop excanvas used for IE 8 support Mads Kiilerich <madski@unity3d.com> parents: 4960 diff changeset	214 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	215 to the extent it is feasible, IE8 is not.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	216
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	217 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	218
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5416 diff changeset	219 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	220 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	221 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	222 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	223 ``display: none``).
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	224
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5416 diff changeset	225 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	226 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	227 ``{}``.
5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5416 diff changeset	228 Variables holding jQuery objects should be named with a leading ``$``.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	229
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	230 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	231 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	232
5432 a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing Mads Kiilerich <madski@unity3d.com> parents: 5425 diff changeset	233 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	234 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	235
a4c0fe15a6f1 docs: contributing.rst clarification of American English and Title Casing Mads Kiilerich <madski@unity3d.com> parents: 5425 diff changeset	236 .. _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	237
6315 2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	238 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	239 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	240 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	241 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	242
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	243 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	244 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	245
6315 2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	246 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	247 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	248 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	249 current session for the active thread. Many database operations are methods on
8323 2b8892f92b46 docs: fix contributing.rst reference to Session.remove() Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	250 such session instances. The session will generally be removed by
2b8892f92b46 docs: fix contributing.rst reference to Session.remove() Mads Kiilerich <mads@kiilerich.com> parents: 8209 diff changeset	251 TurboGears automatically.
6639 2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly Mads Kiilerich <mads@kiilerich.com> parents: 6629 diff changeset	252
2db16cda05ba docs: clarify that Session usually should be called - methods should not be used directly Mads Kiilerich <mads@kiilerich.com> parents: 6629 diff changeset	253 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	254 (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	255 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	256 (but also means that they cannot be shared across requests).
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	257
6315 2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	258 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	259 rarely needed:
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	260
6315 2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	261 * 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	262 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	263
2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	264 * 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	265 ``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	266 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	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 * 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	269 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	270 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	271 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	272 objects it knows about and syncs them to the database.
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	273
6315 2d5fecba40ed docs: add code guidelines on template helpers and the SQLAlchemy session Søren Løvborg <sorenl@unity3d.com> parents: 6314 diff changeset	274 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	275 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	276 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	277 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	278 be ``None``).
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	279
8358 4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	280 Debugging
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	281 ^^^^^^^^^
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	282
8371 3b1c53643b09 doc: fix wording of debug hint in contributing.rst Mads Kiilerich <mads@kiilerich.com> parents: 8358 diff changeset	283 A good way to trace what Kallithea is doing is to keep an eye on the output on
3b1c53643b09 doc: fix wording of debug hint in contributing.rst Mads Kiilerich <mads@kiilerich.com> parents: 8358 diff changeset	284 stdout/stderr of the server process. Perhaps change ``my.ini`` to log at
8358 4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	285 ``DEBUG`` or ``INFO`` level, especially ``[logger_kallithea]``, but perhaps
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	286 also other loggers. It is often easier to add additional ``log`` or ``print``
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	287 statements than to use a Python debugger.
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	288
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	289 Sometimes it is simpler to disable ``errorpage.enabled`` and perhaps also
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	290 ``trace_errors.enable`` to expose raw errors instead of adding extra
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	291 processing. Enabling ``debug`` can be helpful for showing and exploring
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	292 tracebacks in the browser, but is also insecure and will add extra processing.
4869a8bb1237 ini: tweak template configuration for TG's handling of application errors Mads Kiilerich <mads@kiilerich.com> parents: 8323 diff changeset	293
6571 908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	294 TurboGears2 DebugBar
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	295 ^^^^^^^^^^^^^^^^^^^^
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	296
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	297 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	298 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	299
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	300 * 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	301 * 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	302 variables
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	303 * 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	304
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	305 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	306 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	307 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	308 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	309
908e186abd8d backend: add TurboGears2 DebugBar support Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 6555 diff changeset	310 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	311 ``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	312
5433 fbbe80e3322b docs: consistent spacing around headings Mads Kiilerich <madski@unity3d.com> parents: 5432 diff changeset	313
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	314 "Roadmap"
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	315 ---------
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	316
4928 b08aab61c41d docs/contributing: move 'roadmap' to the wiki Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> parents: 4927 diff changeset	317 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	318 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	319 areas are very welcome.
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	320
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	321
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	322 Thank you for your contribution!
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	323 --------------------------------
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	324
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	325
03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	326 .. _Weblate: http://weblate.org/
5425 5ae8e644aa88 docs: spelling, grammar, content and typography Søren Løvborg <sorenl@unity3d.com> parents: 5416 diff changeset	327 .. _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	328 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests
1123 9472a0150bf0 docs update Marcin Kuzminski <marcin@python-works.com> parents: 1092 diff changeset	329 .. _bitbucket: http://bitbucket.org/
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	330 .. _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	331 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
4902 03bbd33bc084 docs: rework stuff Mads Kiilerich <madski@unity3d.com> parents: 4522 diff changeset	332 .. _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	333 .. _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	334 .. _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	335 .. _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	336 .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides

Mercurial > kallithea

annotate docs/contributing.rst @ 8594:3c503044e9f1