Mercurial > kallithea

comparison docs/contributing.rst @ 6735:49be3b49c8e2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs/contributing: make contribution information more accessible Try to make the contribution information more accessible to new users, by giving a bit more detail about the different steps in making contributions. Some rework of the original patch done by Thomas De Schampheleire: - don't give the impression that Bitbucket is mandatory - don't recommend creating feature branches for regular development - reword/cross-reference section on contribution flow
author Karl Goetz <karl@kgoetz.id.au>
date Wed, 28 Jun 2017 21:52:35 +0200
parents 043621a79cdb
children 1daec1628e0b
comparison
equal deleted inserted replaced
6734:c5512c9d2118 6735:49be3b49c8e2
26 26
27 27
28 Getting started 28 Getting started
29 --------------- 29 ---------------
30 30
31 To get started with development:: 31 To get started with Kallithea development::
32 32
33 hg clone https://kallithea-scm.org/repos/kallithea 33 hg clone https://kallithea-scm.org/repos/kallithea
34 cd kallithea 34 cd kallithea
35 virtualenv ../kallithea-venv 35 virtualenv ../kallithea-venv
36 source ../kallithea-venv/bin/activate 36 source ../kallithea-venv/bin/activate
39 gearbox make-config my.ini 39 gearbox make-config my.ini
40 gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp 40 gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp
41 gearbox serve -c my.ini --reload & 41 gearbox serve -c my.ini --reload &
42 firefox http://127.0.0.1:5000/ 42 firefox http://127.0.0.1:5000/
43 43
44 You can also start out by forking https://bitbucket.org/conservancy/kallithea 44 If you plan to use Bitbucket_ for sending contributions, you can also fork
45 on Bitbucket_ and create a local clone of your own fork. 45 Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and
46 then replace the clone step above by a clone of your fork. In this case, please
47 see :ref:`contributing-guidelies` below for configuring your fork correctly.
48
49
50 Contribution flow
51 -----------------
52
53 Starting from an existing Kallithea clone, make sure it is up to date with the
54 latest upstream changes::
55
56 hg pull
57 hg update
58
59 Review the :ref:`contributing-guidelines` and :ref:`coding-guidelines`.
60
61 If you are new to Mercurial, refer to Mercurial `Quick Start`_ and `Beginners
62 Guide`_ on the Mercurial wiki.
63
64 Now, make some changes and test them (see :ref:`contributing-tests`). Don't
65 forget to add new tests to cover new functionality or bug fixes.
66
67 For documentation changes, run ``make html`` from the ``docs`` directory to
68 generate the HTML result, then review them in your browser.
69
70 Before submitting any changes, run the cleanup script::
71
72 ./scripts/run-all-cleanup
73
74 When you are completely ready, you can send your changes to the community for
75 review and inclusion. Most commonly used methods are sending patches to the
76 mailing list (via ``hg email``) or by creating a pull request on Bitbucket_.
77
78 .. _contributing-tests:
46 79
47 80
48 Running tests 81 Running tests
49 ------------- 82 -------------
50 83
112 To analyze performance, you could install pytest-profiling_, which enables the 145 To analyze performance, you could install pytest-profiling_, which enables the
113 --profile and --profile-svg options to py.test. 146 --profile and --profile-svg options to py.test.
114 147
115 .. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling 148 .. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling
116 149
150 .. _contributing-guidelines:
151
117 152
118 Contribution guidelines 153 Contribution guidelines
119 ----------------------- 154 -----------------------
120 155
121 Kallithea is GPLv3 and we assume all contributions are made by the 156 Kallithea is GPLv3 and we assume all contributions are made by the
150 be handled more casually. 185 be handled more casually.
151 186
152 For now we just have one official branch ("default") and will keep it so stable 187 For now we just have one official branch ("default") and will keep it so stable
153 that it can be (and is) used in production. Experimental changes should live 188 that it can be (and is) used in production. Experimental changes should live
154 elsewhere (for example in a pull request) until they are ready. 189 elsewhere (for example in a pull request) until they are ready.
190
191 .. _coding-guidelines:
155 192
156 193
157 Coding guidelines 194 Coding guidelines
158 ----------------- 195 -----------------
159 196
270 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general 307 .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
271 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general 308 .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general
272 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/ 309 .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/
273 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home 310 .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home
274 .. _DebugBar: https://github.com/TurboGears/tgext.debugbar 311 .. _DebugBar: https://github.com/TurboGears/tgext.debugbar
312 .. _Quick Start: https://www.mercurial-scm.org/wiki/QuickStart
313 .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides