Mercurial > kallithea
annotate docs/contributing.rst @ 5770:82f818616265
db: cache SCM instance short-term (tied to SQLAlchemy session lifetime)
Repeatedly checking whether SCM instances are invalidated is slow, and
we don't actually _want_ SCM instances to invalidate half-way through
a request either.
Therefore cache them in on the db.Repository object, the lifetime
of which is directly tied to the lifetime of the SQLAlchemy session,
the lifetime of which is tied directly to the individual HTTP request.
This way, we only check for invalidation the first time the SCM instance
is accessed in a request.
This will improve performance in cases where we have (by definition) badly
written code that retrieves repo objects several times.
author | Søren Løvborg <sorenl@unity3d.com> |
---|---|
date | Tue, 08 Mar 2016 12:28:06 +0100 |
parents | d5e16407bdbb |
children | e45f5dbc2533 |
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 | |
51 After finishing your changes make sure all tests pass cleanly. You can run | |
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
52 the testsuite running ``py.test`` from the project root, or if you use tox |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
53 run ``tox`` for Python 2.6--2.7 with multiple database test. |
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
54 |
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
55 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
|
56 SQLite database specified there. |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
57 |
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
58 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
|
59 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
|
60 |
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
61 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
|
62 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
|
63 kill -9 $(cat test.pid) |
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
64 |
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
65 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
|
66 |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
67 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
|
68 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
|
69 |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
70 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
|
71 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
|
72 are:: |
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
73 |
5701
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
74 -k EXPRESSION only run tests which match the given substring |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
75 expression. An expression is a python evaluatable |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
76 expression where all names are substring-matched |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
77 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
|
78 -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
|
79 --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
|
80 all if none failed) |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
81 --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
|
82 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
|
83 setup/teardown |
2d2decce586f
pytest migration: update documentation
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
5519
diff
changeset
|
84 --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
|
85 -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
|
86 printed immediately) |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
87 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
88 |
4902 | 89 Coding/contribution guidelines |
90 ------------------------------ | |
91 | |
92 Kallithea is GPLv3 and we assume all contributions are made by the | |
93 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
94 lot about preservation of copyright and license information for existing code | |
95 that is brought into the project. | |
96 | |
97 We don't have a formal coding/formatting standard. We are currently using a mix | |
98 of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and | |
99 consistency with existing code. Run whitespacecleanup.sh to avoid stupid | |
100 whitespace noise in your patches. | |
101 | |
102 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
103 about Python 3 compatibility. | |
104 | |
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
105 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
|
106 to the extent it is feasible, IE8 is not. |
4902 | 107 |
108 We primarily support Linux and OS X on the server side but Windows should also work. | |
109 | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
110 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
4902 | 111 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
|
112 semantic markup with element classes and IDs that can be used for styling and testing. |
4902 | 113 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
|
114 ``display: none``). |
4902 | 115 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
116 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
|
117 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
|
118 ``{}``. |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
119 Variables holding jQuery objects should be named with a leading ``$``. |
4902 | 120 |
121 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
|
122 bug fixes, put ``(Issue #123)`` at the end of this line. |
4902 | 123 |
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
124 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
|
125 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
|
126 |
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
127 .. _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
|
128 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
129 Contributions will be accepted in most formats -- such as pull requests on |
4902 | 130 bitbucket, something hosted on your own Kallithea instance, or patches sent by |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
131 email to the `kallithea-general`_ mailing list. |
4902 | 132 |
133 Make sure to test your changes both manually and with the automatic tests | |
134 before posting. | |
135 | |
136 We care about quality and review and keeping a clean repository history. We | |
137 might give feedback that requests polishing contributions until they are | |
138 "perfect". We might also rebase and collapse and make minor adjustments to your | |
139 changes when we apply them. | |
140 | |
141 We try to make sure we have consensus on the direction the project is taking. | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
142 Everything non-sensitive should be discussed in public -- preferably on the |
4902 | 143 mailing list. We aim at having all non-trivial changes reviewed by at least |
144 one other core developer before pushing. Obvious non-controversial changes will | |
145 be handled more casually. | |
146 | |
147 For now we just have one official branch ("default") and will keep it so stable | |
148 that it can be (and is) used in production. Experimental changes should live | |
149 elsewhere (for example in a pull request) until they are ready. | |
1123 | 150 |
4960
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
151 .. _translations: |
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
152 .. include:: ./../kallithea/i18n/how_to |
1123 | 153 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
154 |
4902 | 155 "Roadmap" |
156 --------- | |
157 | |
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
158 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
|
159 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
|
160 areas are very welcome. |
4902 | 161 |
162 | |
163 Thank you for your contribution! | |
164 -------------------------------- | |
165 | |
166 | |
167 .. _Weblate: http://weblate.org/ | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
168 .. _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
|
169 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
1123 | 170 .. _bitbucket: http://bitbucket.org/ |
4902 | 171 .. _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
|
172 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
4902 | 173 .. _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
|
174 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |