Mercurial > kallithea
annotate docs/contributing.rst @ 5458:dd676aab3b4d
auth: use HMAC-SHA1 to calculate password reset token
The use of standard cryptographic primitives is always preferable, and
in this case allows us not to worry about length extension attacks
and possibly any number of issues that I'm not presently aware of.
Also fix a potential Unicode encoding problem.
author | Søren Løvborg <sorenl@unity3d.com> |
---|---|
date | Wed, 02 Sep 2015 17:47:03 +0200 |
parents | fbbe80e3322b |
children | ae9ab4c92d46 |
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 | |
37 python setup.py develop | |
38 paster make-config Kallithea my.ini | |
39 paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp | |
40 paster serve my.ini --reload & | |
41 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
|
42 |
4902 | 43 You can also start out by forking https://bitbucket.org/conservancy/kallithea |
44 on Bitbucket_ and create a local clone of your own fork. | |
45 | |
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
46 |
4902 | 47 Running tests |
48 ------------- | |
49 | |
50 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
|
51 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
|
52 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
|
53 |
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
54 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
|
55 SQLite database specified there. |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
56 |
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
57 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
|
58 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
|
59 |
5416
19267f233d39
tests: move test.ini to kallithea/tests/
Mads Kiilerich <madski@unity3d.com>
parents:
5412
diff
changeset
|
60 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
|
61 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
|
62 kill -9 $(cat test.pid) |
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
63 |
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
64 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
|
65 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
|
66 are:: |
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
67 |
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
68 -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
|
69 -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
|
70 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
|
71 --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
|
72 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
73 |
4902 | 74 Coding/contribution guidelines |
75 ------------------------------ | |
76 | |
77 Kallithea is GPLv3 and we assume all contributions are made by the | |
78 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
79 lot about preservation of copyright and license information for existing code | |
80 that is brought into the project. | |
81 | |
82 We don't have a formal coding/formatting standard. We are currently using a mix | |
83 of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and | |
84 consistency with existing code. Run whitespacecleanup.sh to avoid stupid | |
85 whitespace noise in your patches. | |
86 | |
87 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
88 about Python 3 compatibility. | |
89 | |
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
90 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
|
91 to the extent it is feasible, IE8 is not. |
4902 | 92 |
93 We primarily support Linux and OS X on the server side but Windows should also work. | |
94 | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
95 HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
4902 | 96 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
|
97 semantic markup with element classes and IDs that can be used for styling and testing. |
4902 | 98 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
|
99 ``display: none``). |
4902 | 100 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
101 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
|
102 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
|
103 ``{}``. |
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
104 Variables holding jQuery objects should be named with a leading ``$``. |
4902 | 105 |
106 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
|
107 bug fixes, put ``(Issue #123)`` at the end of this line. |
4902 | 108 |
5432
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
109 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
|
110 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
|
111 |
a4c0fe15a6f1
docs: contributing.rst clarification of American English and Title Casing
Mads Kiilerich <madski@unity3d.com>
parents:
5425
diff
changeset
|
112 .. _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
|
113 |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
114 Contributions will be accepted in most formats -- such as pull requests on |
4902 | 115 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
|
116 email to the `kallithea-general`_ mailing list. |
4902 | 117 |
118 Make sure to test your changes both manually and with the automatic tests | |
119 before posting. | |
120 | |
121 We care about quality and review and keeping a clean repository history. We | |
122 might give feedback that requests polishing contributions until they are | |
123 "perfect". We might also rebase and collapse and make minor adjustments to your | |
124 changes when we apply them. | |
125 | |
126 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
|
127 Everything non-sensitive should be discussed in public -- preferably on the |
4902 | 128 mailing list. We aim at having all non-trivial changes reviewed by at least |
129 one other core developer before pushing. Obvious non-controversial changes will | |
130 be handled more casually. | |
131 | |
132 For now we just have one official branch ("default") and will keep it so stable | |
133 that it can be (and is) used in production. Experimental changes should live | |
134 elsewhere (for example in a pull request) until they are ready. | |
1123 | 135 |
4960
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
136 .. _translations: |
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
137 .. include:: ./../kallithea/i18n/how_to |
1123 | 138 |
5433
fbbe80e3322b
docs: consistent spacing around headings
Mads Kiilerich <madski@unity3d.com>
parents:
5432
diff
changeset
|
139 |
4902 | 140 "Roadmap" |
141 --------- | |
142 | |
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
143 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
|
144 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
|
145 areas are very welcome. |
4902 | 146 |
147 | |
148 Thank you for your contribution! | |
149 -------------------------------- | |
150 | |
151 | |
152 .. _Weblate: http://weblate.org/ | |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
5416
diff
changeset
|
153 .. _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
|
154 .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
1123 | 155 .. _bitbucket: http://bitbucket.org/ |
4902 | 156 .. _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
|
157 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
4902 | 158 .. _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
|
159 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |