Mercurial > kallithea
annotate docs/contributing.rst @ 4927:f879e7ea1c4b
docs/contributing: explicitly mention some useful options to nosetests
| author | Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> |
|---|---|
| date | Tue, 17 Mar 2015 20:53:50 +0100 |
| parents | ef63850d1144 |
| children | b08aab61c41d |
| 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 |
| 19 issue tracker is for tracking bugs, not for "support", discussion or ideas - | |
| 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. | |
| 24 To register, you can use your Bitbucket or GitHub account. | |
| 25 | |
|
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 | |
| 88 We try to support the most common modern web browsers. IE8 is still supported | |
| 89 to the extent it is feasible but we may stop supporting it very soon. | |
| 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 | |
| 108 mail to the kallithea-general mailing list. | |
| 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 |
| 128 | |
| 4902 | 129 "Roadmap" |
| 130 --------- | |
| 131 | |
| 132 We do not have a road map but are waiting for your contributions. Here are some | |
| 133 ideas of places we might want to go - contributions in these areas are very | |
| 134 welcome: | |
| 135 | |
| 136 * Front end: | |
| 137 * kill YUI - more jQuery | |
| 138 * remove other dependencies - especially the embedded cut'n'pasted ones | |
| 139 * remove hardcoded styling in templates, make markup more semantic while moving all styling to css | |
| 140 * switch to bootstrap or some other modern UI library and cleanup of style.css and contextbar.css | |
| 141 * new fancy style that looks good | |
| 142 * testing | |
| 143 * better test coverage with the existing high level test framework | |
| 144 * test even more high level and javascript - selenium/robot and splinter seems like the top candidates | |
| 145 * more unit testing | |
| 146 * code cleanup | |
| 147 * move code from templates to controllers and from controllers to libs or models | |
| 148 * more best practice for web apps and the frameworks | |
| 149 * features | |
| 150 * relax dependency version requirements after thorough testing | |
| 151 * support for evolve | |
| 152 * updates of PRs ... while preserving history and comment context | |
| 153 * auto pr merge/rebase | |
| 154 * ssh | |
| 155 * bitbucket compatible wiki | |
| 156 * realtime preview / wysiwyg when editing comments and files | |
| 157 * make journal more useful - filtering on branches and files | |
| 158 * community mode with self registration and personal space | |
| 159 * improve documentation | |
| 160 | |
| 161 Thank you for your contribution! | |
| 162 -------------------------------- | |
| 163 | |
| 164 | |
| 165 .. _Weblate: http://weblate.org/ | |
| 166 .. _Issue Tracker: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open | |
| 167 .. _Pull Requests: https://bitbucket.org/conservancy/kallithea/pull-requests | |
| 1123 | 168 .. _bitbucket: http://bitbucket.org/ |
| 4902 | 169 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
| 170 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/ |