Mercurial > kallithea
annotate docs/contributing.rst @ 5445:322e17eb356a
changelog: rework changeset selection and button behaviour
This is a refactoring / rework of messy code to be simpler and work correctly.
As a result, it gives slightly different behaviour in some cases and different
button labels.
It also allows creating PRs after selecting two changesets. That is currently
pointless but will make sense soon.
| author | Mads Kiilerich <madski@unity3d.com> |
|---|---|
| date | Wed, 26 Aug 2015 17:28:59 +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 |