Mercurial > kallithea
annotate docs/contributing.rst @ 6474:2ff913970025
journal: make "username:" filtering condition work as expected
As described in previous revision, using TEXT in JOURNAL_SCHEMA causes
unexpected results for "username:", too.
- tokenization by non-alphanumeric characters
- removing "stop words"
To make "username:" filtering condition work as expected, this
revision uses ID instead of TEST for "username" of JOURNAL_COLUMN.
| author | FUJIWARA Katsunori <foozy@lares.dti.ne.jp> |
|---|---|
| date | Mon, 23 Jan 2017 02:17:38 +0900 |
| parents | 9c6f717823e1 |
| children | 2c3d30095d5e |
| rev | line source |
|---|---|
| 811 | 1 .. _contributing: |
| 2 | |
| 2095 | 3 ========================= |
|
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
4 Contributing to Kallithea |
| 811 | 5 ========================= |
| 6 | |
| 4902 | 7 Kallithea is developed and maintained by its users. Please join us and scratch |
| 8 your own itch. | |
| 9 | |
| 10 | |
| 11 Infrastructure | |
| 12 -------------- | |
| 811 | 13 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
14 The main repository is hosted on Our Own Kallithea (aka OOK) at |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
15 https://kallithea-scm.org/repos/kallithea/, our self-hosted instance |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
16 of Kallithea. |
|
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
811
diff
changeset
|
17 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
18 For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
19 issue tracker is for tracking bugs, not for support, discussion, or ideas -- |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
20 please use the `mailing list`_ or :ref:`IRC <readme>` to reach the community. |
| 4902 | 21 |
| 22 We use Weblate_ to translate the user interface messages into languages other | |
| 23 than English. Join our project on `Hosted Weblate`_ to help us. | |
|
4960
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
24 To register, you can use your Bitbucket or GitHub account. See :ref:`translations` |
|
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
25 for more details. |
|
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
26 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
27 |
| 4902 | 28 Getting started |
| 29 --------------- | |
|
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
811
diff
changeset
|
30 |
| 4902 | 31 To get started with development:: |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
32 |
| 4902 | 33 hg clone https://kallithea-scm.org/repos/kallithea |
| 34 cd kallithea | |
| 35 virtualenv ../kallithea-venv | |
| 36 source ../kallithea-venv/bin/activate | |
|
5519
8c234ae2c258
docs: add advice of upgrading pip and setuptools in new virtualenvs
Mads Kiilerich <madski@unity3d.com>
parents:
5502
diff
changeset
|
37 pip install --upgrade pip setuptools |
|
5755
250f8150c4bb
docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents:
5519
diff
changeset
|
38 pip install -e . |
| 4902 | 39 paster make-config Kallithea my.ini |
| 40 paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp | |
| 41 paster serve my.ini --reload & | |
| 42 firefox http://127.0.0.1:5000/ | |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
43 |
| 4902 | 44 You can also start out by forking https://bitbucket.org/conservancy/kallithea |
| 45 on Bitbucket_ and create a local clone of your own fork. | |
| 46 | |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
47 |
| 4902 | 48 Running tests |
| 49 ------------- | |
| 50 | |
|
6026
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
51 After finishing your changes make sure all tests pass cleanly. Install the test |
|
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
52 dependencies, then run the testsuite by invoking ``py.test`` from the |
|
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
53 project root:: |
|
5959
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
54 |
|
6026
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
55 pip install -r dev_requirements.txt |
|
5959
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
56 py.test |
|
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
57 |
|
6026
dd676fdeda0f
setup: move test dependencies to dev_requirements.txt to make them optional
Mads Kiilerich <madski@unity3d.com>
parents:
5972
diff
changeset
|
58 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
|
59 |
|
5959
e6fafb5ed70d
docs: make the default method for running tests more visible
Mads Kiilerich <madski@unity3d.com>
parents:
5885
diff
changeset
|
60 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
|
61 (currently Python 2.6--2.7). |
|
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
62 |
|
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
63 When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the |
|
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
64 SQLite database specified there. |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
65 |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
66 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
|
67 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
|
68 |
|
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
69 paster serve kallithea/tests/test.ini --pid-file=test.pid --daemon |
|
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
70 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
|
71 kill -9 $(cat test.pid) |
|
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
72 |
|
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
73 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
|
74 |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
75 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
|
76 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
|
77 |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
78 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
|
79 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
|
80 are:: |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
81 |
|
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
82 -k EXPRESSION only run tests which match the given substring |
| 5835 | 83 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
|
84 expression where all names are substring-matched |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
85 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
|
86 -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
|
87 --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
|
88 all if none failed) |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
89 --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
|
90 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
|
91 setup/teardown |
|
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
92 --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
|
93 -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
|
94 printed immediately) |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
95 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
96 |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
97 Contribution guidelines |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
98 ----------------------- |
| 4902 | 99 |
| 100 Kallithea is GPLv3 and we assume all contributions are made by the | |
| 101 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
| 102 lot about preservation of copyright and license information for existing code | |
| 103 that is brought into the project. | |
| 104 | |
|
6314
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
105 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
|
106 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
|
107 email to the `kallithea-general`_ mailing list. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
108 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
109 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
|
110 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
|
111 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
|
112 "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
|
113 maintainers to integrate your changes. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
114 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
115 .. _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
|
116 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
117 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
|
118 before posting. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
119 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
120 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
|
121 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
|
122 "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
|
123 changes when we apply them. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
124 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
125 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
|
126 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
|
127 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
|
128 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
|
129 be handled more casually. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
130 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
131 For now we just have one official branch ("default") and will keep it so stable |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
132 that it can be (and is) used in production. Experimental changes should live |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
133 elsewhere (for example in a pull request) until they are ready. |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
134 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
135 |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
136 Coding guidelines |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
137 ----------------- |
|
50f1a6adbefd
docs: separate coding/contribution guidelines
Søren Løvborg <sorenl@unity3d.com>
parents:
6026
diff
changeset
|
138 |
| 4902 | 139 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
|
140 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
|
141 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
|
142 committing to ensure some basic code formatting consistency. |
| 4902 | 143 |
| 144 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
| 145 about Python 3 compatibility. | |
| 146 | |
|
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
147 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
|
148 to the extent it is feasible, IE8 is not. |
| 4902 | 149 |
| 150 We primarily support Linux and OS X on the server side but Windows should also work. | |
| 151 | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
152 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
| 4902 | 153 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
|
154 semantic markup with element classes and IDs that can be used for styling and testing. |
| 4902 | 155 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
|
156 ``display: none``). |
| 4902 | 157 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
158 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
|
159 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
|
160 ``{}``. |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
161 Variables holding jQuery objects should be named with a leading ``$``. |
| 4902 | 162 |
| 163 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
|
164 bug fixes, put ``(Issue #123)`` at the end of this line. |
| 4902 | 165 |
|
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
166 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
|
167 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
|
168 |
|
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
169 .. _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
|
170 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
171 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
|
172 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
|
173 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
|
174 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
|
175 |
|
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
176 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
|
177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4902 | 178 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
179 Each HTTP request runs inside an independent SQLAlchemy session (as well |
|
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
180 as in an independent database transaction). Database model objects |
|
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
181 (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
|
182 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
|
183 (but also means that they cannot be shared across requests). |
| 4902 | 184 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
185 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
|
186 rarely needed: |
| 4902 | 187 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
188 * 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
|
189 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
|
190 |
|
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
191 * 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
|
192 ``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
|
193 been added to the session, and should not be added again. |
| 4902 | 194 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
195 * 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
|
196 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
|
197 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
|
198 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
|
199 objects it knows about and syncs them to the database. |
| 1123 | 200 |
|
6315
2d5fecba40ed
docs: add code guidelines on template helpers and the SQLAlchemy session
Søren Løvborg <sorenl@unity3d.com>
parents:
6314
diff
changeset
|
201 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
|
202 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
|
203 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
|
204 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
|
205 be ``None``). |
| 1123 | 206 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
207 |
| 4902 | 208 "Roadmap" |
| 209 --------- | |
| 210 | |
|
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
211 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
|
212 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
|
213 areas are very welcome. |
| 4902 | 214 |
| 215 | |
| 216 Thank you for your contribution! | |
| 217 -------------------------------- | |
| 218 | |
| 219 | |
| 220 .. _Weblate: http://weblate.org/ | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
221 .. _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
|
222 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
| 1123 | 223 .. _bitbucket: http://bitbucket.org/ |
| 4902 | 224 .. _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
|
225 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
| 4902 | 226 .. _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
|
227 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |