##// END OF EJS Templates
docs/contributing: move 'roadmap' to the wiki...
Thomas De Schampheleire -
r4928:b08aab61 default
parent child Browse files
Show More
@@ -1,170 +1,147 b''
1 1 .. _contributing:
2 2
3 3 =========================
4 4 Contributing to Kallithea
5 5 =========================
6 6
7 7 Kallithea is developed and maintained by its users. Please join us and scratch
8 8 your own itch.
9 9
10 10
11 11 Infrastructure
12 12 --------------
13 13
14 14 The main repository is hosted at Our Own Kallithea (aka OOK) on
15 15 https://kallithea-scm.org/repos/kallithea/ (which is our self-hosted instance
16 16 of Kallithea).
17 17
18 18 For now, we use Bitbucket_ for `Pull Requests`_ and `Issue Tracker`_ services. The
19 19 issue tracker is for tracking bugs, not for "support", discussion or ideas -
20 20 please use the `mailing list`_ to reach the community.
21 21
22 22 We use Weblate_ to translate the user interface messages into languages other
23 23 than English. Join our project on `Hosted Weblate`_ to help us.
24 24 To register, you can use your Bitbucket or GitHub account.
25 25
26 26
27 27 Getting started
28 28 ---------------
29 29
30 30 To get started with development::
31 31
32 32 hg clone https://kallithea-scm.org/repos/kallithea
33 33 cd kallithea
34 34 virtualenv ../kallithea-venv
35 35 source ../kallithea-venv/bin/activate
36 36 python setup.py develop
37 37 paster make-config Kallithea my.ini
38 38 paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp
39 39 paster serve my.ini --reload &
40 40 firefox http://127.0.0.1:5000/
41 41
42 42 You can also start out by forking https://bitbucket.org/conservancy/kallithea
43 43 on Bitbucket_ and create a local clone of your own fork.
44 44
45 45
46 46 Running tests
47 47 -------------
48 48
49 49 After finishing your changes make sure all tests pass cleanly. You can run
50 50 the testsuite running ``nosetests`` from the project root, or if you use tox
51 51 run ``tox`` for python2.6-2.7 with multiple database test.
52 52
53 53 When using `nosetests`, the `test.ini` file is used with an SQLite database. Edit
54 54 this file to change your testing enviroment.
55 55
56 56 It is possible to avoid recreating the full test database on each invocation of
57 57 the tests, thus eliminating the initial delay. To achieve this, run the tests as::
58 58
59 59 paster serve test.ini --pid-file=test.pid --daemon
60 60 KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 nosetests
61 61 kill -9 $(cat test.pid)
62 62
63 63 You can run individual tests by specifying their path as argument to nosetests.
64 64 nosetests also has many more options, see `nosetests -h`. Some useful options
65 65 are::
66 66
67 67 -x, --stop Stop running tests after the first error or failure
68 68 -s, --nocapture Don't capture stdout (any stdout output will be
69 69 printed immediately) [NOSE_NOCAPTURE]
70 70 --failed Run the tests that failed in the last test run.
71 71
72 72 Coding/contribution guidelines
73 73 ------------------------------
74 74
75 75 Kallithea is GPLv3 and we assume all contributions are made by the
76 76 committer/contributor and under GPLv3 unless explicitly stated. We do care a
77 77 lot about preservation of copyright and license information for existing code
78 78 that is brought into the project.
79 79
80 80 We don't have a formal coding/formatting standard. We are currently using a mix
81 81 of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and
82 82 consistency with existing code. Run whitespacecleanup.sh to avoid stupid
83 83 whitespace noise in your patches.
84 84
85 85 We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care
86 86 about Python 3 compatibility.
87 87
88 88 We try to support the most common modern web browsers. IE8 is still supported
89 89 to the extent it is feasible but we may stop supporting it very soon.
90 90
91 91 We primarily support Linux and OS X on the server side but Windows should also work.
92 92
93 93 Html templates should use 2 spaces for indentation ... but be pragmatic. We
94 94 should use templates cleverly and avoid duplication. We should use reasonable
95 95 semantic markup with classes and ids that can be used for styling and testing.
96 96 We should only use inline styles in places where it really is semantic (such as
97 97 display:none).
98 98
99 99 JavaScript must use ';' between/after statements. Indentation 4 spaces. Inline
100 100 multiline functions should be indented two levels - one for the () and one for
101 101 {}. jQuery value arrays should have a leading $.
102 102
103 103 Commit messages should have a leading short line summarizing the changes. For
104 104 bug fixes, put "(Issue #123)" at the end of this line.
105 105
106 106 Contributions will be accepted in most formats - such as pull requests on
107 107 bitbucket, something hosted on your own Kallithea instance, or patches sent by
108 108 mail to the kallithea-general mailing list.
109 109
110 110 Make sure to test your changes both manually and with the automatic tests
111 111 before posting.
112 112
113 113 We care about quality and review and keeping a clean repository history. We
114 114 might give feedback that requests polishing contributions until they are
115 115 "perfect". We might also rebase and collapse and make minor adjustments to your
116 116 changes when we apply them.
117 117
118 118 We try to make sure we have consensus on the direction the project is taking.
119 119 Everything non-sensitive should be discussed in public - preferably on the
120 120 mailing list. We aim at having all non-trivial changes reviewed by at least
121 121 one other core developer before pushing. Obvious non-controversial changes will
122 122 be handled more casually.
123 123
124 124 For now we just have one official branch ("default") and will keep it so stable
125 125 that it can be (and is) used in production. Experimental changes should live
126 126 elsewhere (for example in a pull request) until they are ready.
127 127
128 128
129 129 "Roadmap"
130 130 ---------
131 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:
132 We do not have a road map but are waiting for your contributions. Refer to the
133 wiki_ for some ideas of places we might want to go - contributions in these
134 areas are very welcome.
135 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 136
161 137 Thank you for your contribution!
162 138 --------------------------------
163 139
164 140
165 141 .. _Weblate: http://weblate.org/
166 142 .. _Issue Tracker: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open
167 143 .. _Pull Requests: https://bitbucket.org/conservancy/kallithea/pull-requests
168 144 .. _bitbucket: http://bitbucket.org/
169 145 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
170 146 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/
147 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home
General Comments 0
You need to be logged in to leave comments. Login now