Mercurial > kallithea
annotate docs/contributing.rst @ 5414:d9386a3924db
vcs: invalidate repo caches _after_ a push finishes
Caches were invalidated right after creating the result iterator, before
actually applying the change. Caches would thus be refreshed too early and soon
be outdated.
This bug was especially seen causing errors with missing revisions when
creating PRs right after pushing.
| author | Mads Kiilerich <madski@unity3d.com> |
|---|---|
| date | Thu, 20 Aug 2015 17:29:55 +0200 |
| parents | 2079e864ce51 |
| children | 19267f233d39 |
| 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 |
| 4902 | 14 The main repository is hosted at Our Own Kallithea (aka OOK) on |
| 15 https://kallithea-scm.org/repos/kallithea/ (which is our self-hosted instance | |
| 16 of Kallithea). | |
|
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
811
diff
changeset
|
17 |
| 4902 | 18 For now, we use Bitbucket_ for `Pull Requests`_ and `Issue Tracker`_ services. The |
|
4955
4e6dfdb3fa01
docs: English and consistency corrections
Michael V. DePalatis <mike@depalatis.net>
parents:
4928
diff
changeset
|
19 issue tracker is for tracking bugs, not for support, discussion, or ideas - |
| 4902 | 20 please use the `mailing list`_ to reach the community. |
| 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 |
| 4902 | 27 Getting started |
| 28 --------------- | |
|
1062
053983a464e4
docs and readme update
Marcin Kuzminski <marcin@python-works.com>
parents:
811
diff
changeset
|
29 |
| 4902 | 30 To get started with development:: |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
31 |
| 4902 | 32 hg clone https://kallithea-scm.org/repos/kallithea |
| 33 cd kallithea | |
| 34 virtualenv ../kallithea-venv | |
| 35 source ../kallithea-venv/bin/activate | |
| 36 python setup.py develop | |
| 37 paster make-config Kallithea my.ini | |
| 38 paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp | |
| 39 paster serve my.ini --reload & | |
| 40 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
|
41 |
| 4902 | 42 You can also start out by forking https://bitbucket.org/conservancy/kallithea |
| 43 on Bitbucket_ and create a local clone of your own fork. | |
| 44 | |
|
2032
950110f3f99f
merged changes from stable into beta
Marcin Kuzminski <marcin@python-works.com>
parents:
1123
diff
changeset
|
45 |
| 4902 | 46 Running tests |
| 47 ------------- | |
| 48 | |
| 49 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
|
50 the testsuite running ``nosetests`` from the project root, or if you use tox |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
51 run ``tox`` for python2.6-2.7 with multiple database test. |
|
3993
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
52 |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
53 When using `nosetests`, the `test.ini` file is used with an SQLite database. Edit |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
54 this file to change your testing enviroment. |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
55 |
|
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
56 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
|
57 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
|
58 |
|
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
59 paster serve 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
|
60 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
|
61 kill -9 $(cat test.pid) |
|
b53cef6faf22
updated contributing docs
Marcin Kuzminski <marcin@python-works.com>
parents:
3700
diff
changeset
|
62 |
|
4920
329dd2b2025d
docs/contributing: cleanup test section
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4914
diff
changeset
|
63 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
|
64 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
|
65 are:: |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
66 |
|
f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4926
diff
changeset
|
67 -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
|
68 -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
|
69 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
|
70 --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
|
71 |
| 4902 | 72 Coding/contribution guidelines |
| 73 ------------------------------ | |
| 74 | |
| 75 Kallithea is GPLv3 and we assume all contributions are made by the | |
| 76 committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
| 77 lot about preservation of copyright and license information for existing code | |
| 78 that is brought into the project. | |
| 79 | |
| 80 We don't have a formal coding/formatting standard. We are currently using a mix | |
| 81 of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and | |
| 82 consistency with existing code. Run whitespacecleanup.sh to avoid stupid | |
| 83 whitespace noise in your patches. | |
| 84 | |
| 85 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
| 86 about Python 3 compatibility. | |
| 87 | |
|
5308
b8d716694dc8
js: drop excanvas used for IE 8 support
Mads Kiilerich <madski@unity3d.com>
parents:
4960
diff
changeset
|
88 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
|
89 to the extent it is feasible, IE8 is not. |
| 4902 | 90 |
| 91 We primarily support Linux and OS X on the server side but Windows should also work. | |
| 92 | |
| 93 Html templates should use 2 spaces for indentation ... but be pragmatic. We | |
| 94 should use templates cleverly and avoid duplication. We should use reasonable | |
| 95 semantic markup with classes and ids that can be used for styling and testing. | |
| 96 We should only use inline styles in places where it really is semantic (such as | |
| 97 display:none). | |
| 98 | |
| 99 JavaScript must use ';' between/after statements. Indentation 4 spaces. Inline | |
| 100 multiline functions should be indented two levels - one for the () and one for | |
| 101 {}. jQuery value arrays should have a leading $. | |
| 102 | |
| 103 Commit messages should have a leading short line summarizing the changes. For | |
| 104 bug fixes, put "(Issue #123)" at the end of this line. | |
| 105 | |
| 106 Contributions will be accepted in most formats - such as pull requests on | |
| 107 bitbucket, something hosted on your own Kallithea instance, or patches sent by | |
|
5412
2079e864ce51
spelling: use "email" consistently
Søren Løvborg <sorenl@unity3d.com>
parents:
5308
diff
changeset
|
108 email to the kallithea-general mailing list. |
| 4902 | 109 |
| 110 Make sure to test your changes both manually and with the automatic tests | |
| 111 before posting. | |
| 112 | |
| 113 We care about quality and review and keeping a clean repository history. We | |
| 114 might give feedback that requests polishing contributions until they are | |
| 115 "perfect". We might also rebase and collapse and make minor adjustments to your | |
| 116 changes when we apply them. | |
| 117 | |
| 118 We try to make sure we have consensus on the direction the project is taking. | |
| 119 Everything non-sensitive should be discussed in public - preferably on the | |
| 120 mailing list. We aim at having all non-trivial changes reviewed by at least | |
| 121 one other core developer before pushing. Obvious non-controversial changes will | |
| 122 be handled more casually. | |
| 123 | |
| 124 For now we just have one official branch ("default") and will keep it so stable | |
| 125 that it can be (and is) used in production. Experimental changes should live | |
| 126 elsewhere (for example in a pull request) until they are ready. | |
| 1123 | 127 |
|
4960
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
128 .. _translations: |
|
f4857279cb29
docs: include translation howto into the docco
Andrew Shadura <andrew@shadura.me>
parents:
4955
diff
changeset
|
129 .. include:: ./../kallithea/i18n/how_to |
| 1123 | 130 |
| 4902 | 131 "Roadmap" |
| 132 --------- | |
| 133 | |
|
4928
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
134 We do not have a road map but are waiting for your contributions. Refer to the |
|
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
135 wiki_ for some ideas of places we might want to go - contributions in these |
|
b08aab61c41d
docs/contributing: move 'roadmap' to the wiki
Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
parents:
4927
diff
changeset
|
136 areas are very welcome. |
| 4902 | 137 |
| 138 | |
| 139 Thank you for your contribution! | |
| 140 -------------------------------- | |
| 141 | |
| 142 | |
| 143 .. _Weblate: http://weblate.org/ | |
| 144 .. _Issue Tracker: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open | |
| 145 .. _Pull Requests: https://bitbucket.org/conservancy/kallithea/pull-requests | |
| 1123 | 146 .. _bitbucket: http://bitbucket.org/ |
| 4902 | 147 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
| 148 .. _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
|
149 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |