Mercurial > kallithea
annotate docs/contributing.rst @ 5633:83f7b5449860
db: stop messing with convert_unicode in .ini and db scheme
convert_unicode=False is the default for String fields ... except when the .ini file contains sets it to True.
String fields are however no longer used for unicode and we can drop convert_unicode everywhere.
See
http://docs.sqlalchemy.org/en/latest/core/type_basics.html#sqlalchemy.types.String.params.convert_unicode
for the advice of never setting convert_unicode.
| author | Mads Kiilerich <madski@unity3d.com> |
|---|---|
| date | Tue, 05 Jan 2016 16:30:12 +0100 |
| parents | 8c234ae2c258 |
| children | 2d2decce586f 250f8150c4bb |
| 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 |
|
5502
ae9ab4c92d46
setup: explicitly use python2 in examples in the documentation
Mads Kiilerich <madski@unity3d.com>
parents:
5433
diff
changeset
|
38 python2 setup.py develop |
| 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 | |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
52 the testsuite running ``nosetests`` 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 |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
62 KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 nosetests |
|
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 |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
65 You can run individual tests by specifying their path as argument to nosetests. |
|
4927
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
66 nosetests also has many more options, see `nosetests -h`. Some useful options |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
67 are:: |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
68 |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
69 -x, --stop Stop running tests after the first error or failure |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
70 -s, --nocapture Don't capture stdout (any stdout output will be |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
71 printed immediately) [NOSE_NOCAPTURE] |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
72 --failed Run the tests that failed in the last test run. |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
73 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
74 |
| 4902 | 75 Coding/contribution guidelines |
| 76 ------------------------------ | |
| 77 | |
| 78 Kallithea is GPLv3 and we assume all contributions are made by the | |
| 79 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
| 80 lot about preservation of copyright and license information for existing code | |
| 81 that is brought into the project. | |
| 82 | |
| 83 We don't have a formal coding/formatting standard. We are currently using a mix | |
| 84 of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and | |
| 85 consistency with existing code. Run whitespacecleanup.sh to avoid stupid | |
| 86 whitespace noise in your patches. | |
| 87 | |
| 88 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
| 89 about Python 3 compatibility. | |
| 90 | |
|
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
91 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
|
92 to the extent it is feasible, IE8 is not. |
| 4902 | 93 |
| 94 We primarily support Linux and OS X on the server side but Windows should also work. | |
| 95 | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
96 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
| 4902 | 97 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
|
98 semantic markup with element classes and IDs that can be used for styling and testing. |
| 4902 | 99 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
|
100 ``display: none``). |
| 4902 | 101 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
102 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
|
103 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
|
104 ``{}``. |
|
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
105 Variables holding jQuery objects should be named with a leading ``$``. |
| 4902 | 106 |
| 107 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
|
108 bug fixes, put ``(Issue #123)`` at the end of this line. |
| 4902 | 109 |
|
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
110 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
|
111 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
|
112 |
|
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
113 .. _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
|
114 |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
115 Contributions will be accepted in most formats -- such as pull requests on |
| 4902 | 116 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
|
117 email to the `kallithea-general`_ mailing list. |
| 4902 | 118 |
| 119 Make sure to test your changes both manually and with the automatic tests | |
| 120 before posting. | |
| 121 | |
| 122 We care about quality and review and keeping a clean repository history. We | |
| 123 might give feedback that requests polishing contributions until they are | |
| 124 "perfect". We might also rebase and collapse and make minor adjustments to your | |
| 125 changes when we apply them. | |
| 126 | |
| 127 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
|
128 Everything non-sensitive should be discussed in public -- preferably on the |
| 4902 | 129 mailing list. We aim at having all non-trivial changes reviewed by at least |
| 130 one other core developer before pushing. Obvious non-controversial changes will | |
| 131 be handled more casually. | |
| 132 | |
| 133 For now we just have one official branch ("default") and will keep it so stable | |
| 134 that it can be (and is) used in production. Experimental changes should live | |
| 135 elsewhere (for example in a pull request) until they are ready. | |
| 1123 | 136 |
|
4960
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
137 .. _translations: |
|
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
138 .. include:: ./../kallithea/i18n/how_to |
| 1123 | 139 |
|
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
140 |
| 4902 | 141 "Roadmap" |
| 142 --------- | |
| 143 | |
|
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
144 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
|
145 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
|
146 areas are very welcome. |
| 4902 | 147 |
| 148 | |
| 149 Thank you for your contribution! | |
| 150 -------------------------------- | |
| 151 | |
| 152 | |
| 153 .. _Weblate: http://weblate.org/ | |
|
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
154 .. _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
|
155 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
| 1123 | 156 .. _bitbucket: http://bitbucket.org/ |
| 4902 | 157 .. _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
|
158 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
| 4902 | 159 .. _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
|
160 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |