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