Show More
@@ -1,314 +1,314 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 on Our Own Kallithea (aka OOK) at |
|
14 | The main repository is hosted on Our Own Kallithea (aka OOK) at | |
15 | https://kallithea-scm.org/repos/kallithea/, our self-hosted instance |
|
15 | https://kallithea-scm.org/repos/kallithea/, our self-hosted instance | |
16 | of Kallithea. |
|
16 | of Kallithea. | |
17 |
|
17 | |||
18 | For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The |
|
18 | For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. 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`_ or :ref:`IRC <readme>` to reach the community. |
|
20 | please use the `mailing list`_ or :ref:`IRC <readme>` 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. See :ref:`translations` |
|
24 | To register, you can use your Bitbucket or GitHub account. See :ref:`translations` | |
25 | for more details. |
|
25 | for more details. | |
26 |
|
26 | |||
27 |
|
27 | |||
28 | Getting started |
|
28 | Getting started | |
29 | --------------- |
|
29 | --------------- | |
30 |
|
30 | |||
31 | To get started with Kallithea 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 | |
37 | pip install --upgrade pip setuptools |
|
37 | pip install --upgrade pip setuptools | |
38 | pip install -e . |
|
38 | pip install --upgrade -e . | |
39 | pip install -r dev_requirements.txt |
|
39 | pip install --upgrade -r dev_requirements.txt | |
40 | gearbox make-config my.ini |
|
40 | gearbox make-config my.ini | |
41 | gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp |
|
41 | gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp | |
42 | gearbox serve -c my.ini --reload & |
|
42 | gearbox serve -c my.ini --reload & | |
43 | firefox http://127.0.0.1:5000/ |
|
43 | firefox http://127.0.0.1:5000/ | |
44 |
|
44 | |||
45 | If you plan to use Bitbucket_ for sending contributions, you can also fork |
|
45 | If you plan to use Bitbucket_ for sending contributions, you can also fork | |
46 | Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and |
|
46 | Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and | |
47 | then replace the clone step above by a clone of your fork. In this case, please |
|
47 | then replace the clone step above by a clone of your fork. In this case, please | |
48 | see :ref:`contributing-guidelies` below for configuring your fork correctly. |
|
48 | see :ref:`contributing-guidelies` below for configuring your fork correctly. | |
49 |
|
49 | |||
50 |
|
50 | |||
51 | Contribution flow |
|
51 | Contribution flow | |
52 | ----------------- |
|
52 | ----------------- | |
53 |
|
53 | |||
54 | Starting from an existing Kallithea clone, make sure it is up to date with the |
|
54 | Starting from an existing Kallithea clone, make sure it is up to date with the | |
55 | latest upstream changes:: |
|
55 | latest upstream changes:: | |
56 |
|
56 | |||
57 | hg pull |
|
57 | hg pull | |
58 | hg update |
|
58 | hg update | |
59 |
|
59 | |||
60 | Review the :ref:`contributing-guidelines` and :ref:`coding-guidelines`. |
|
60 | Review the :ref:`contributing-guidelines` and :ref:`coding-guidelines`. | |
61 |
|
61 | |||
62 | If you are new to Mercurial, refer to Mercurial `Quick Start`_ and `Beginners |
|
62 | If you are new to Mercurial, refer to Mercurial `Quick Start`_ and `Beginners | |
63 | Guide`_ on the Mercurial wiki. |
|
63 | Guide`_ on the Mercurial wiki. | |
64 |
|
64 | |||
65 | Now, make some changes and test them (see :ref:`contributing-tests`). Don't |
|
65 | Now, make some changes and test them (see :ref:`contributing-tests`). Don't | |
66 | forget to add new tests to cover new functionality or bug fixes. |
|
66 | forget to add new tests to cover new functionality or bug fixes. | |
67 |
|
67 | |||
68 | For documentation changes, run ``make html`` from the ``docs`` directory to |
|
68 | For documentation changes, run ``make html`` from the ``docs`` directory to | |
69 | generate the HTML result, then review them in your browser. |
|
69 | generate the HTML result, then review them in your browser. | |
70 |
|
70 | |||
71 | Before submitting any changes, run the cleanup script:: |
|
71 | Before submitting any changes, run the cleanup script:: | |
72 |
|
72 | |||
73 | ./scripts/run-all-cleanup |
|
73 | ./scripts/run-all-cleanup | |
74 |
|
74 | |||
75 | When you are completely ready, you can send your changes to the community for |
|
75 | When you are completely ready, you can send your changes to the community for | |
76 | review and inclusion. Most commonly used methods are sending patches to the |
|
76 | review and inclusion. Most commonly used methods are sending patches to the | |
77 | mailing list (via ``hg email``) or by creating a pull request on Bitbucket_. |
|
77 | mailing list (via ``hg email``) or by creating a pull request on Bitbucket_. | |
78 |
|
78 | |||
79 | .. _contributing-tests: |
|
79 | .. _contributing-tests: | |
80 |
|
80 | |||
81 |
|
81 | |||
82 | Running tests |
|
82 | Running tests | |
83 | ------------- |
|
83 | ------------- | |
84 |
|
84 | |||
85 | After finishing your changes make sure all tests pass cleanly. Run the testsuite |
|
85 | After finishing your changes make sure all tests pass cleanly. Run the testsuite | |
86 | by invoking ``py.test`` from the project root:: |
|
86 | by invoking ``py.test`` from the project root:: | |
87 |
|
87 | |||
88 | py.test |
|
88 | py.test | |
89 |
|
89 | |||
90 | Note that testing on Python 2.6 also requires ``unittest2``. |
|
90 | Note that testing on Python 2.6 also requires ``unittest2``. | |
91 |
|
91 | |||
92 | Note that on unix systems, the temporary directory (``/tmp`` or where |
|
92 | Note that on unix systems, the temporary directory (``/tmp`` or where | |
93 | ``$TMPDIR`` points) must allow executable files; Git hooks must be executable, |
|
93 | ``$TMPDIR`` points) must allow executable files; Git hooks must be executable, | |
94 | and the test suite creates repositories in the temporary directory. Linux |
|
94 | and the test suite creates repositories in the temporary directory. Linux | |
95 | systems with /tmp mounted noexec will thus fail. |
|
95 | systems with /tmp mounted noexec will thus fail. | |
96 |
|
96 | |||
97 | You can also use ``tox`` to run the tests with all supported Python versions |
|
97 | You can also use ``tox`` to run the tests with all supported Python versions | |
98 | (currently Python 2.6--2.7). |
|
98 | (currently Python 2.6--2.7). | |
99 |
|
99 | |||
100 | When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the |
|
100 | When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the | |
101 | SQLite database specified there. |
|
101 | SQLite database specified there. | |
102 |
|
102 | |||
103 | It is possible to avoid recreating the full test database on each invocation of |
|
103 | It is possible to avoid recreating the full test database on each invocation of | |
104 | the tests, thus eliminating the initial delay. To achieve this, run the tests as:: |
|
104 | the tests, thus eliminating the initial delay. To achieve this, run the tests as:: | |
105 |
|
105 | |||
106 | gearbox serve -c kallithea/tests/test.ini --pid-file=test.pid --daemon |
|
106 | gearbox serve -c kallithea/tests/test.ini --pid-file=test.pid --daemon | |
107 | KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 py.test |
|
107 | KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 py.test | |
108 | kill -9 $(cat test.pid) |
|
108 | kill -9 $(cat test.pid) | |
109 |
|
109 | |||
110 | In these commands, the following variables are used:: |
|
110 | In these commands, the following variables are used:: | |
111 |
|
111 | |||
112 | KALLITHEA_WHOOSH_TEST_DISABLE=1 - skip whoosh index building and tests |
|
112 | KALLITHEA_WHOOSH_TEST_DISABLE=1 - skip whoosh index building and tests | |
113 | KALLITHEA_NO_TMP_PATH=1 - disable new temp path for tests, used mostly for testing_vcs_operations |
|
113 | KALLITHEA_NO_TMP_PATH=1 - disable new temp path for tests, used mostly for testing_vcs_operations | |
114 |
|
114 | |||
115 | You can run individual tests by specifying their path as argument to py.test. |
|
115 | You can run individual tests by specifying their path as argument to py.test. | |
116 | py.test also has many more options, see `py.test -h`. Some useful options |
|
116 | py.test also has many more options, see `py.test -h`. Some useful options | |
117 | are:: |
|
117 | are:: | |
118 |
|
118 | |||
119 | -k EXPRESSION only run tests which match the given substring |
|
119 | -k EXPRESSION only run tests which match the given substring | |
120 | expression. An expression is a python evaluable |
|
120 | expression. An expression is a python evaluable | |
121 | expression where all names are substring-matched |
|
121 | expression where all names are substring-matched | |
122 | against test names and their parent classes. Example: |
|
122 | against test names and their parent classes. Example: | |
123 | -x, --exitfirst exit instantly on first error or failed test. |
|
123 | -x, --exitfirst exit instantly on first error or failed test. | |
124 | --lf rerun only the tests that failed at the last run (or |
|
124 | --lf rerun only the tests that failed at the last run (or | |
125 | all if none failed) |
|
125 | all if none failed) | |
126 | --ff run all tests but run the last failures first. This |
|
126 | --ff run all tests but run the last failures first. This | |
127 | may re-order tests and thus lead to repeated fixture |
|
127 | may re-order tests and thus lead to repeated fixture | |
128 | setup/teardown |
|
128 | setup/teardown | |
129 | --pdb start the interactive Python debugger on errors. |
|
129 | --pdb start the interactive Python debugger on errors. | |
130 | -s, --capture=no don't capture stdout (any stdout output will be |
|
130 | -s, --capture=no don't capture stdout (any stdout output will be | |
131 | printed immediately) |
|
131 | printed immediately) | |
132 |
|
132 | |||
133 | Performance tests |
|
133 | Performance tests | |
134 | ^^^^^^^^^^^^^^^^^ |
|
134 | ^^^^^^^^^^^^^^^^^ | |
135 |
|
135 | |||
136 | A number of performance tests are present in the test suite, but they are |
|
136 | A number of performance tests are present in the test suite, but they are | |
137 | not run in a standard test run. These tests are useful to |
|
137 | not run in a standard test run. These tests are useful to | |
138 | evaluate the impact of certain code changes with respect to performance. |
|
138 | evaluate the impact of certain code changes with respect to performance. | |
139 |
|
139 | |||
140 | To run these tests:: |
|
140 | To run these tests:: | |
141 |
|
141 | |||
142 | env TEST_PERFORMANCE=1 py.test kallithea/tests/performance |
|
142 | env TEST_PERFORMANCE=1 py.test kallithea/tests/performance | |
143 |
|
143 | |||
144 | To analyze performance, you could install pytest-profiling_, which enables the |
|
144 | To analyze performance, you could install pytest-profiling_, which enables the | |
145 | --profile and --profile-svg options to py.test. |
|
145 | --profile and --profile-svg options to py.test. | |
146 |
|
146 | |||
147 | .. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling |
|
147 | .. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling | |
148 |
|
148 | |||
149 | .. _contributing-guidelines: |
|
149 | .. _contributing-guidelines: | |
150 |
|
150 | |||
151 |
|
151 | |||
152 | Contribution guidelines |
|
152 | Contribution guidelines | |
153 | ----------------------- |
|
153 | ----------------------- | |
154 |
|
154 | |||
155 | Kallithea is GPLv3 and we assume all contributions are made by the |
|
155 | Kallithea is GPLv3 and we assume all contributions are made by the | |
156 | committer/contributor and under GPLv3 unless explicitly stated. We do care a |
|
156 | committer/contributor and under GPLv3 unless explicitly stated. We do care a | |
157 | lot about preservation of copyright and license information for existing code |
|
157 | lot about preservation of copyright and license information for existing code | |
158 | that is brought into the project. |
|
158 | that is brought into the project. | |
159 |
|
159 | |||
160 | Contributions will be accepted in most formats -- such as pull requests on |
|
160 | Contributions will be accepted in most formats -- such as pull requests on | |
161 | Bitbucket, something hosted on your own Kallithea instance, or patches sent by |
|
161 | Bitbucket, something hosted on your own Kallithea instance, or patches sent by | |
162 | email to the `kallithea-general`_ mailing list. |
|
162 | email to the `kallithea-general`_ mailing list. | |
163 |
|
163 | |||
164 | When contributing via Bitbucket, please make your fork of |
|
164 | When contributing via Bitbucket, please make your fork of | |
165 | https://bitbucket.org/conservancy/kallithea/ `non-publishing`_ -- it is one of |
|
165 | https://bitbucket.org/conservancy/kallithea/ `non-publishing`_ -- it is one of | |
166 | the settings on "Repository details" page. This ensures your commits are in |
|
166 | the settings on "Repository details" page. This ensures your commits are in | |
167 | "draft" phase and makes it easier for you to address feedback and for project |
|
167 | "draft" phase and makes it easier for you to address feedback and for project | |
168 | maintainers to integrate your changes. |
|
168 | maintainers to integrate your changes. | |
169 |
|
169 | |||
170 | .. _non-publishing: https://www.mercurial-scm.org/wiki/Phases#Publishing_Repository |
|
170 | .. _non-publishing: https://www.mercurial-scm.org/wiki/Phases#Publishing_Repository | |
171 |
|
171 | |||
172 | Make sure to test your changes both manually and with the automatic tests |
|
172 | Make sure to test your changes both manually and with the automatic tests | |
173 | before posting. |
|
173 | before posting. | |
174 |
|
174 | |||
175 | We care about quality and review and keeping a clean repository history. We |
|
175 | We care about quality and review and keeping a clean repository history. We | |
176 | might give feedback that requests polishing contributions until they are |
|
176 | might give feedback that requests polishing contributions until they are | |
177 | "perfect". We might also rebase and collapse and make minor adjustments to your |
|
177 | "perfect". We might also rebase and collapse and make minor adjustments to your | |
178 | changes when we apply them. |
|
178 | changes when we apply them. | |
179 |
|
179 | |||
180 | We try to make sure we have consensus on the direction the project is taking. |
|
180 | We try to make sure we have consensus on the direction the project is taking. | |
181 | Everything non-sensitive should be discussed in public -- preferably on the |
|
181 | Everything non-sensitive should be discussed in public -- preferably on the | |
182 | mailing list. We aim at having all non-trivial changes reviewed by at least |
|
182 | mailing list. We aim at having all non-trivial changes reviewed by at least | |
183 | one other core developer before pushing. Obvious non-controversial changes will |
|
183 | one other core developer before pushing. Obvious non-controversial changes will | |
184 | be handled more casually. |
|
184 | be handled more casually. | |
185 |
|
185 | |||
186 | There is a main development branch ("default") which is generally stable so that |
|
186 | There is a main development branch ("default") which is generally stable so that | |
187 | it can be (and is) used in production. There is also a "stable" branch that is |
|
187 | it can be (and is) used in production. There is also a "stable" branch that is | |
188 | almost exclusively reserved for bug fixes or trivial changes. Experimental |
|
188 | almost exclusively reserved for bug fixes or trivial changes. Experimental | |
189 | changes should live elsewhere (for example in a pull request) until they are |
|
189 | changes should live elsewhere (for example in a pull request) until they are | |
190 | ready. |
|
190 | ready. | |
191 |
|
191 | |||
192 | .. _coding-guidelines: |
|
192 | .. _coding-guidelines: | |
193 |
|
193 | |||
194 |
|
194 | |||
195 | Coding guidelines |
|
195 | Coding guidelines | |
196 | ----------------- |
|
196 | ----------------- | |
197 |
|
197 | |||
198 | We don't have a formal coding/formatting standard. We are currently using a mix |
|
198 | We don't have a formal coding/formatting standard. We are currently using a mix | |
199 | of Mercurial's (https://www.mercurial-scm.org/wiki/CodingStyle), pep8, and |
|
199 | of Mercurial's (https://www.mercurial-scm.org/wiki/CodingStyle), pep8, and | |
200 | consistency with existing code. Run ``scripts/run-all-cleanup`` before |
|
200 | consistency with existing code. Run ``scripts/run-all-cleanup`` before | |
201 | committing to ensure some basic code formatting consistency. |
|
201 | committing to ensure some basic code formatting consistency. | |
202 |
|
202 | |||
203 | We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care |
|
203 | We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care | |
204 | about Python 3 compatibility. |
|
204 | about Python 3 compatibility. | |
205 |
|
205 | |||
206 | We try to support the most common modern web browsers. IE9 is still supported |
|
206 | We try to support the most common modern web browsers. IE9 is still supported | |
207 | to the extent it is feasible, IE8 is not. |
|
207 | to the extent it is feasible, IE8 is not. | |
208 |
|
208 | |||
209 | We primarily support Linux and OS X on the server side but Windows should also work. |
|
209 | We primarily support Linux and OS X on the server side but Windows should also work. | |
210 |
|
210 | |||
211 | HTML templates should use 2 spaces for indentation ... but be pragmatic. We |
|
211 | HTML templates should use 2 spaces for indentation ... but be pragmatic. We | |
212 | should use templates cleverly and avoid duplication. We should use reasonable |
|
212 | should use templates cleverly and avoid duplication. We should use reasonable | |
213 | semantic markup with element classes and IDs that can be used for styling and testing. |
|
213 | semantic markup with element classes and IDs that can be used for styling and testing. | |
214 | We should only use inline styles in places where it really is semantic (such as |
|
214 | We should only use inline styles in places where it really is semantic (such as | |
215 | ``display: none``). |
|
215 | ``display: none``). | |
216 |
|
216 | |||
217 | JavaScript must use ``;`` between/after statements. Indentation 4 spaces. Inline |
|
217 | JavaScript must use ``;`` between/after statements. Indentation 4 spaces. Inline | |
218 | multiline functions should be indented two levels -- one for the ``()`` and one for |
|
218 | multiline functions should be indented two levels -- one for the ``()`` and one for | |
219 | ``{}``. |
|
219 | ``{}``. | |
220 | Variables holding jQuery objects should be named with a leading ``$``. |
|
220 | Variables holding jQuery objects should be named with a leading ``$``. | |
221 |
|
221 | |||
222 | Commit messages should have a leading short line summarizing the changes. For |
|
222 | Commit messages should have a leading short line summarizing the changes. For | |
223 | bug fixes, put ``(Issue #123)`` at the end of this line. |
|
223 | bug fixes, put ``(Issue #123)`` at the end of this line. | |
224 |
|
224 | |||
225 | Use American English grammar and spelling overall. Use `English title case`_ for |
|
225 | Use American English grammar and spelling overall. Use `English title case`_ for | |
226 | page titles, button labels, headers, and 'labels' for fields in forms. |
|
226 | page titles, button labels, headers, and 'labels' for fields in forms. | |
227 |
|
227 | |||
228 | .. _English title case: https://en.wikipedia.org/wiki/Capitalization#Title_case |
|
228 | .. _English title case: https://en.wikipedia.org/wiki/Capitalization#Title_case | |
229 |
|
229 | |||
230 | Template helpers (that is, everything in ``kallithea.lib.helpers``) |
|
230 | Template helpers (that is, everything in ``kallithea.lib.helpers``) | |
231 | should only be referenced from templates. If you need to call a |
|
231 | should only be referenced from templates. If you need to call a | |
232 | helper from the Python code, consider moving the function somewhere |
|
232 | helper from the Python code, consider moving the function somewhere | |
233 | else (e.g. to the model). |
|
233 | else (e.g. to the model). | |
234 |
|
234 | |||
235 | Notes on the SQLAlchemy session |
|
235 | Notes on the SQLAlchemy session | |
236 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
236 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
237 |
|
237 | |||
238 | Each HTTP request runs inside an independent SQLAlchemy session (as well |
|
238 | Each HTTP request runs inside an independent SQLAlchemy session (as well | |
239 | as in an independent database transaction). ``Session`` is the session manager |
|
239 | as in an independent database transaction). ``Session`` is the session manager | |
240 | and factory. ``Session()`` will create a new session on-demand or return the |
|
240 | and factory. ``Session()`` will create a new session on-demand or return the | |
241 | current session for the active thread. Many database operations are methods on |
|
241 | current session for the active thread. Many database operations are methods on | |
242 | such session instances - only ``Session.remove()`` should be called directly on |
|
242 | such session instances - only ``Session.remove()`` should be called directly on | |
243 | the manager. |
|
243 | the manager. | |
244 |
|
244 | |||
245 | Database model objects |
|
245 | Database model objects | |
246 | (almost) always belong to a particular SQLAlchemy session, which means |
|
246 | (almost) always belong to a particular SQLAlchemy session, which means | |
247 | that SQLAlchemy will ensure that they're kept in sync with the database |
|
247 | that SQLAlchemy will ensure that they're kept in sync with the database | |
248 | (but also means that they cannot be shared across requests). |
|
248 | (but also means that they cannot be shared across requests). | |
249 |
|
249 | |||
250 | Objects can be added to the session using ``Session().add``, but this is |
|
250 | Objects can be added to the session using ``Session().add``, but this is | |
251 | rarely needed: |
|
251 | rarely needed: | |
252 |
|
252 | |||
253 | * When creating a database object by calling the constructor directly, |
|
253 | * When creating a database object by calling the constructor directly, | |
254 | it must explicitly be added to the session. |
|
254 | it must explicitly be added to the session. | |
255 |
|
255 | |||
256 | * When creating an object using a factory function (like |
|
256 | * When creating an object using a factory function (like | |
257 | ``create_repo``), the returned object has already (by convention) |
|
257 | ``create_repo``), the returned object has already (by convention) | |
258 | been added to the session, and should not be added again. |
|
258 | been added to the session, and should not be added again. | |
259 |
|
259 | |||
260 | * When getting an object from the session (via ``Session().query`` or |
|
260 | * When getting an object from the session (via ``Session().query`` or | |
261 | any of the utility functions that look up objects in the database), |
|
261 | any of the utility functions that look up objects in the database), | |
262 | it's already part of the session, and should not be added again. |
|
262 | it's already part of the session, and should not be added again. | |
263 | SQLAlchemy monitors attribute modifications automatically for all |
|
263 | SQLAlchemy monitors attribute modifications automatically for all | |
264 | objects it knows about and syncs them to the database. |
|
264 | objects it knows about and syncs them to the database. | |
265 |
|
265 | |||
266 | SQLAlchemy also flushes changes to the database automatically; manually |
|
266 | SQLAlchemy also flushes changes to the database automatically; manually | |
267 | calling ``Session().flush`` is usually only necessary when the Python |
|
267 | calling ``Session().flush`` is usually only necessary when the Python | |
268 | code needs the database to assign an "auto-increment" primary key ID to |
|
268 | code needs the database to assign an "auto-increment" primary key ID to | |
269 | a freshly created model object (before flushing, the ID attribute will |
|
269 | a freshly created model object (before flushing, the ID attribute will | |
270 | be ``None``). |
|
270 | be ``None``). | |
271 |
|
271 | |||
272 | TurboGears2 DebugBar |
|
272 | TurboGears2 DebugBar | |
273 | ^^^^^^^^^^^^^^^^^^^^ |
|
273 | ^^^^^^^^^^^^^^^^^^^^ | |
274 |
|
274 | |||
275 | It is possible to enable the TurboGears2-provided DebugBar_, a toolbar overlayed |
|
275 | It is possible to enable the TurboGears2-provided DebugBar_, a toolbar overlayed | |
276 | over the Kallithea web interface, allowing you to see: |
|
276 | over the Kallithea web interface, allowing you to see: | |
277 |
|
277 | |||
278 | * timing information of the current request, including profiling information |
|
278 | * timing information of the current request, including profiling information | |
279 | * request data, including GET data, POST data, cookies, headers and environment |
|
279 | * request data, including GET data, POST data, cookies, headers and environment | |
280 | variables |
|
280 | variables | |
281 | * a list of executed database queries, including timing and result values |
|
281 | * a list of executed database queries, including timing and result values | |
282 |
|
282 | |||
283 | DebugBar is only activated when ``debug = true`` is set in the configuration |
|
283 | DebugBar is only activated when ``debug = true`` is set in the configuration | |
284 | file. This is important, because the DebugBar toolbar will be visible for all |
|
284 | file. This is important, because the DebugBar toolbar will be visible for all | |
285 | users, and allow them to see information they should not be allowed to see. Like |
|
285 | users, and allow them to see information they should not be allowed to see. Like | |
286 | is anyway the case for ``debug = true``, do not use this in production! |
|
286 | is anyway the case for ``debug = true``, do not use this in production! | |
287 |
|
287 | |||
288 | To enable DebugBar, install ``tgext.debugbar`` and ``kajiki`` (typically via |
|
288 | To enable DebugBar, install ``tgext.debugbar`` and ``kajiki`` (typically via | |
289 | ``pip``) and restart Kallithea (in debug mode). |
|
289 | ``pip``) and restart Kallithea (in debug mode). | |
290 |
|
290 | |||
291 |
|
291 | |||
292 | "Roadmap" |
|
292 | "Roadmap" | |
293 | --------- |
|
293 | --------- | |
294 |
|
294 | |||
295 | We do not have a road map but are waiting for your contributions. Refer to the |
|
295 | We do not have a road map but are waiting for your contributions. Refer to the | |
296 | wiki_ for some ideas of places we might want to go -- contributions in these |
|
296 | wiki_ for some ideas of places we might want to go -- contributions in these | |
297 | areas are very welcome. |
|
297 | areas are very welcome. | |
298 |
|
298 | |||
299 |
|
299 | |||
300 | Thank you for your contribution! |
|
300 | Thank you for your contribution! | |
301 | -------------------------------- |
|
301 | -------------------------------- | |
302 |
|
302 | |||
303 |
|
303 | |||
304 | .. _Weblate: http://weblate.org/ |
|
304 | .. _Weblate: http://weblate.org/ | |
305 | .. _issue tracking: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open |
|
305 | .. _issue tracking: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open | |
306 | .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests |
|
306 | .. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests | |
307 | .. _bitbucket: http://bitbucket.org/ |
|
307 | .. _bitbucket: http://bitbucket.org/ | |
308 | .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
|
308 | .. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general | |
309 | .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general |
|
309 | .. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general | |
310 | .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/ |
|
310 | .. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/ | |
311 | .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home |
|
311 | .. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home | |
312 | .. _DebugBar: https://github.com/TurboGears/tgext.debugbar |
|
312 | .. _DebugBar: https://github.com/TurboGears/tgext.debugbar | |
313 | .. _Quick Start: https://www.mercurial-scm.org/wiki/QuickStart |
|
313 | .. _Quick Start: https://www.mercurial-scm.org/wiki/QuickStart | |
314 | .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides |
|
314 | .. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides |
@@ -1,139 +1,139 b'' | |||||
1 | .. _installation: |
|
1 | .. _installation: | |
2 |
|
2 | |||
3 | ========================== |
|
3 | ========================== | |
4 | Installation on Unix/Linux |
|
4 | Installation on Unix/Linux | |
5 | ========================== |
|
5 | ========================== | |
6 |
|
6 | |||
7 | The following describes three different ways of installing Kallithea: |
|
7 | The following describes three different ways of installing Kallithea: | |
8 |
|
8 | |||
9 | - :ref:`installation-source`: The simplest way to keep the installation |
|
9 | - :ref:`installation-source`: The simplest way to keep the installation | |
10 | up-to-date and track any local customizations is to run directly from |
|
10 | up-to-date and track any local customizations is to run directly from | |
11 | source in a Kallithea repository clone, preferably inside a virtualenv |
|
11 | source in a Kallithea repository clone, preferably inside a virtualenv | |
12 | virtual Python environment. |
|
12 | virtual Python environment. | |
13 |
|
13 | |||
14 | - :ref:`installation-virtualenv`: If you prefer to only use released versions |
|
14 | - :ref:`installation-virtualenv`: If you prefer to only use released versions | |
15 | of Kallithea, the recommended method is to install Kallithea in a virtual |
|
15 | of Kallithea, the recommended method is to install Kallithea in a virtual | |
16 | Python environment using `virtualenv`. The advantages of this method over |
|
16 | Python environment using `virtualenv`. The advantages of this method over | |
17 | direct installation is that Kallithea and its dependencies are completely |
|
17 | direct installation is that Kallithea and its dependencies are completely | |
18 | contained inside the virtualenv (which also means you can have multiple |
|
18 | contained inside the virtualenv (which also means you can have multiple | |
19 | installations side by side or remove it entirely by just removing the |
|
19 | installations side by side or remove it entirely by just removing the | |
20 | virtualenv directory) and does not require root privileges. |
|
20 | virtualenv directory) and does not require root privileges. | |
21 |
|
21 | |||
22 | - :ref:`installation-without-virtualenv`: The alternative method of installing |
|
22 | - :ref:`installation-without-virtualenv`: The alternative method of installing | |
23 | a Kallithea release is using standard pip. The package will be installed in |
|
23 | a Kallithea release is using standard pip. The package will be installed in | |
24 | the same location as all other Python packages you have ever installed. As a |
|
24 | the same location as all other Python packages you have ever installed. As a | |
25 | result, removing it is not as straightforward as with a virtualenv, as you'd |
|
25 | result, removing it is not as straightforward as with a virtualenv, as you'd | |
26 | have to remove its dependencies manually and make sure that they are not |
|
26 | have to remove its dependencies manually and make sure that they are not | |
27 | needed by other packages. |
|
27 | needed by other packages. | |
28 |
|
28 | |||
29 | Regardless of the installation method you may need to make sure you have |
|
29 | Regardless of the installation method you may need to make sure you have | |
30 | appropriate development packages installed, as installation of some of the |
|
30 | appropriate development packages installed, as installation of some of the | |
31 | Kallithea dependencies requires a working C compiler and libffi library |
|
31 | Kallithea dependencies requires a working C compiler and libffi library | |
32 | headers. Depending on your configuration, you may also need to install |
|
32 | headers. Depending on your configuration, you may also need to install | |
33 | Git and development packages for the database of your choice. |
|
33 | Git and development packages for the database of your choice. | |
34 |
|
34 | |||
35 | For Debian and Ubuntu, the following command will ensure that a reasonable |
|
35 | For Debian and Ubuntu, the following command will ensure that a reasonable | |
36 | set of dependencies is installed:: |
|
36 | set of dependencies is installed:: | |
37 |
|
37 | |||
38 | sudo apt-get install build-essential git python-pip python-virtualenv libffi-dev python-dev |
|
38 | sudo apt-get install build-essential git python-pip python-virtualenv libffi-dev python-dev | |
39 |
|
39 | |||
40 | For Fedora and RHEL-derivatives, the following command will ensure that a |
|
40 | For Fedora and RHEL-derivatives, the following command will ensure that a | |
41 | reasonable set of dependencies is installed:: |
|
41 | reasonable set of dependencies is installed:: | |
42 |
|
42 | |||
43 | sudo yum install gcc git python-pip python-virtualenv libffi-devel python-devel |
|
43 | sudo yum install gcc git python-pip python-virtualenv libffi-devel python-devel | |
44 |
|
44 | |||
45 | .. _installation-source: |
|
45 | .. _installation-source: | |
46 |
|
46 | |||
47 |
|
47 | |||
48 | Installation from repository source |
|
48 | Installation from repository source | |
49 | ----------------------------------- |
|
49 | ----------------------------------- | |
50 |
|
50 | |||
51 | To install Kallithea in a virtualenv_ using the stable branch of the development |
|
51 | To install Kallithea in a virtualenv_ using the stable branch of the development | |
52 | repository, follow the instructions below:: |
|
52 | repository, follow the instructions below:: | |
53 |
|
53 | |||
54 | hg clone https://kallithea-scm.org/repos/kallithea -u stable |
|
54 | hg clone https://kallithea-scm.org/repos/kallithea -u stable | |
55 | cd kallithea |
|
55 | cd kallithea | |
56 | virtualenv ../kallithea-venv |
|
56 | virtualenv ../kallithea-venv | |
57 | . ../kallithea-venv/bin/activate |
|
57 | . ../kallithea-venv/bin/activate | |
58 | pip install --upgrade pip setuptools |
|
58 | pip install --upgrade pip setuptools | |
59 | pip install -e . |
|
59 | pip install --upgrade -e . | |
60 | python2 setup.py compile_catalog # for translation of the UI |
|
60 | python2 setup.py compile_catalog # for translation of the UI | |
61 |
|
61 | |||
62 | You can now proceed to :ref:`setup`. |
|
62 | You can now proceed to :ref:`setup`. | |
63 |
|
63 | |||
64 | .. _installation-virtualenv: |
|
64 | .. _installation-virtualenv: | |
65 |
|
65 | |||
66 |
|
66 | |||
67 | Installing a released version in a virtualenv |
|
67 | Installing a released version in a virtualenv | |
68 | --------------------------------------------- |
|
68 | --------------------------------------------- | |
69 |
|
69 | |||
70 | It is highly recommended to use a separate virtualenv_ for installing Kallithea. |
|
70 | It is highly recommended to use a separate virtualenv_ for installing Kallithea. | |
71 | This way, all libraries required by Kallithea will be installed separately from your |
|
71 | This way, all libraries required by Kallithea will be installed separately from your | |
72 | main Python installation and other applications and things will be less |
|
72 | main Python installation and other applications and things will be less | |
73 | problematic when upgrading the system or Kallithea. |
|
73 | problematic when upgrading the system or Kallithea. | |
74 | An additional benefit of virtualenv_ is that it doesn't require root privileges. |
|
74 | An additional benefit of virtualenv_ is that it doesn't require root privileges. | |
75 |
|
75 | |||
76 | - Assuming you have installed virtualenv_, create a new virtual environment |
|
76 | - Assuming you have installed virtualenv_, create a new virtual environment | |
77 | for example, in `/srv/kallithea/venv`, using the virtualenv command:: |
|
77 | for example, in `/srv/kallithea/venv`, using the virtualenv command:: | |
78 |
|
78 | |||
79 | virtualenv /srv/kallithea/venv |
|
79 | virtualenv /srv/kallithea/venv | |
80 |
|
80 | |||
81 | - Activate the virtualenv_ in your current shell session and make sure the |
|
81 | - Activate the virtualenv_ in your current shell session and make sure the | |
82 | basic requirements are up-to-date by running:: |
|
82 | basic requirements are up-to-date by running:: | |
83 |
|
83 | |||
84 | . /srv/kallithea/venv/bin/activate |
|
84 | . /srv/kallithea/venv/bin/activate | |
85 | pip install --upgrade pip setuptools |
|
85 | pip install --upgrade pip setuptools | |
86 |
|
86 | |||
87 | .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it |
|
87 | .. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it | |
88 | will "activate" a shell that terminates immediately. It is also perfectly |
|
88 | will "activate" a shell that terminates immediately. It is also perfectly | |
89 | acceptable (and desirable) to create a virtualenv as a normal user. |
|
89 | acceptable (and desirable) to create a virtualenv as a normal user. | |
90 |
|
90 | |||
91 | .. note:: Some dependencies are optional. If you need them, install them in |
|
91 | .. note:: Some dependencies are optional. If you need them, install them in | |
92 | the virtualenv too:: |
|
92 | the virtualenv too:: | |
93 |
|
93 | |||
94 | pip install psycopg2 |
|
94 | pip install --upgrade psycopg2 | |
95 | pip install python-ldap |
|
95 | pip install --upgrade python-ldap | |
96 |
|
96 | |||
97 | This might require installation of development packages using your |
|
97 | This might require installation of development packages using your | |
98 | distribution's package manager. |
|
98 | distribution's package manager. | |
99 |
|
99 | |||
100 | - Make a folder for Kallithea data files, and configuration somewhere on the |
|
100 | - Make a folder for Kallithea data files, and configuration somewhere on the | |
101 | filesystem. For example:: |
|
101 | filesystem. For example:: | |
102 |
|
102 | |||
103 | mkdir /srv/kallithea |
|
103 | mkdir /srv/kallithea | |
104 |
|
104 | |||
105 | - Go into the created directory and run this command to install Kallithea:: |
|
105 | - Go into the created directory and run this command to install Kallithea:: | |
106 |
|
106 | |||
107 | pip install kallithea |
|
107 | pip install --upgrade kallithea | |
108 |
|
108 | |||
109 | Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea, |
|
109 | Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea, | |
110 | extract it and run:: |
|
110 | extract it and run:: | |
111 |
|
111 | |||
112 | pip install . |
|
112 | pip install --upgrade . | |
113 |
|
113 | |||
114 | - This will install Kallithea together with all other required |
|
114 | - This will install Kallithea together with all other required | |
115 | Python libraries into the activated virtualenv. |
|
115 | Python libraries into the activated virtualenv. | |
116 |
|
116 | |||
117 | You can now proceed to :ref:`setup`. |
|
117 | You can now proceed to :ref:`setup`. | |
118 |
|
118 | |||
119 | .. _installation-without-virtualenv: |
|
119 | .. _installation-without-virtualenv: | |
120 |
|
120 | |||
121 |
|
121 | |||
122 | Installing a released version without virtualenv |
|
122 | Installing a released version without virtualenv | |
123 | ------------------------------------------------ |
|
123 | ------------------------------------------------ | |
124 |
|
124 | |||
125 | For installation without virtualenv, 'just' use:: |
|
125 | For installation without virtualenv, 'just' use:: | |
126 |
|
126 | |||
127 | pip install kallithea |
|
127 | pip install kallithea | |
128 |
|
128 | |||
129 | Note that this method requires root privileges and will install packages |
|
129 | Note that this method requires root privileges and will install packages | |
130 | globally without using the system's package manager. |
|
130 | globally without using the system's package manager. | |
131 |
|
131 | |||
132 | To install as a regular user in ``~/.local``, you can use:: |
|
132 | To install as a regular user in ``~/.local``, you can use:: | |
133 |
|
133 | |||
134 | pip install --user kallithea |
|
134 | pip install --user kallithea | |
135 |
|
135 | |||
136 | You can now proceed to :ref:`setup`. |
|
136 | You can now proceed to :ref:`setup`. | |
137 |
|
137 | |||
138 |
|
138 | |||
139 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
139 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
@@ -1,185 +1,185 b'' | |||||
1 | .. _upgrade: |
|
1 | .. _upgrade: | |
2 |
|
2 | |||
3 | =================== |
|
3 | =================== | |
4 | Upgrading Kallithea |
|
4 | Upgrading Kallithea | |
5 | =================== |
|
5 | =================== | |
6 |
|
6 | |||
7 | This describes the process for upgrading Kallithea, independently of the |
|
7 | This describes the process for upgrading Kallithea, independently of the | |
8 | Kallithea installation method. |
|
8 | Kallithea installation method. | |
9 |
|
9 | |||
10 | .. note:: |
|
10 | .. note:: | |
11 | If you are upgrading from a RhodeCode installation, you must first |
|
11 | If you are upgrading from a RhodeCode installation, you must first | |
12 | install Kallithea 0.3.2 and follow the instructions in the 0.3.2 |
|
12 | install Kallithea 0.3.2 and follow the instructions in the 0.3.2 | |
13 | README to perform a one-time conversion of the database from |
|
13 | README to perform a one-time conversion of the database from | |
14 | RhodeCode to Kallithea, before upgrading to the latest version |
|
14 | RhodeCode to Kallithea, before upgrading to the latest version | |
15 | of Kallithea. |
|
15 | of Kallithea. | |
16 |
|
16 | |||
17 |
|
17 | |||
18 | 1. Stop the Kallithea web application |
|
18 | 1. Stop the Kallithea web application | |
19 | ------------------------------------- |
|
19 | ------------------------------------- | |
20 |
|
20 | |||
21 | This step depends entirely on the web server software used to serve |
|
21 | This step depends entirely on the web server software used to serve | |
22 | Kallithea, but in any case, Kallithea should not be running during |
|
22 | Kallithea, but in any case, Kallithea should not be running during | |
23 | the upgrade. |
|
23 | the upgrade. | |
24 |
|
24 | |||
25 | .. note:: |
|
25 | .. note:: | |
26 | If you're using Celery, make sure you stop all instances during the |
|
26 | If you're using Celery, make sure you stop all instances during the | |
27 | upgrade. |
|
27 | upgrade. | |
28 |
|
28 | |||
29 |
|
29 | |||
30 | 2. Create a backup of both database and configuration |
|
30 | 2. Create a backup of both database and configuration | |
31 | ----------------------------------------------------- |
|
31 | ----------------------------------------------------- | |
32 |
|
32 | |||
33 | You are of course strongly recommended to make backups regularly, but it |
|
33 | You are of course strongly recommended to make backups regularly, but it | |
34 | is *especially* important to make a full database and configuration |
|
34 | is *especially* important to make a full database and configuration | |
35 | backup before performing a Kallithea upgrade. |
|
35 | backup before performing a Kallithea upgrade. | |
36 |
|
36 | |||
37 | Back up your configuration |
|
37 | Back up your configuration | |
38 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
38 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
39 |
|
39 | |||
40 | Make a copy of your Kallithea configuration (``.ini``) file. |
|
40 | Make a copy of your Kallithea configuration (``.ini``) file. | |
41 |
|
41 | |||
42 | If you are using :ref:`rcextensions <customization>`, you should also |
|
42 | If you are using :ref:`rcextensions <customization>`, you should also | |
43 | make a copy of the entire ``rcextensions`` directory. |
|
43 | make a copy of the entire ``rcextensions`` directory. | |
44 |
|
44 | |||
45 | Back up your database |
|
45 | Back up your database | |
46 | ^^^^^^^^^^^^^^^^^^^^^ |
|
46 | ^^^^^^^^^^^^^^^^^^^^^ | |
47 |
|
47 | |||
48 | If using SQLite, simply make a copy of the Kallithea database (``.db``) |
|
48 | If using SQLite, simply make a copy of the Kallithea database (``.db``) | |
49 | file. |
|
49 | file. | |
50 |
|
50 | |||
51 | If using PostgreSQL, please consult the documentation for the ``pg_dump`` |
|
51 | If using PostgreSQL, please consult the documentation for the ``pg_dump`` | |
52 | utility. |
|
52 | utility. | |
53 |
|
53 | |||
54 | If using MySQL, please consult the documentation for the ``mysqldump`` |
|
54 | If using MySQL, please consult the documentation for the ``mysqldump`` | |
55 | utility. |
|
55 | utility. | |
56 |
|
56 | |||
57 | Look for ``sqlalchemy.url`` in your configuration file to determine |
|
57 | Look for ``sqlalchemy.url`` in your configuration file to determine | |
58 | database type, settings, location, etc. |
|
58 | database type, settings, location, etc. | |
59 |
|
59 | |||
60 |
|
60 | |||
61 | 3. Activate the Kallithea virtual environment (if any) |
|
61 | 3. Activate the Kallithea virtual environment (if any) | |
62 | ------------------------------------------------------ |
|
62 | ------------------------------------------------------ | |
63 |
|
63 | |||
64 | Verify that you are using the Python environment that you originally |
|
64 | Verify that you are using the Python environment that you originally | |
65 | installed Kallithea in by running:: |
|
65 | installed Kallithea in by running:: | |
66 |
|
66 | |||
67 | pip freeze |
|
67 | pip freeze | |
68 |
|
68 | |||
69 | This will list all packages installed in the current environment. If |
|
69 | This will list all packages installed in the current environment. If | |
70 | Kallithea isn't listed, activate the correct virtual environment. |
|
70 | Kallithea isn't listed, activate the correct virtual environment. | |
71 | See the appropriate installation page for details. |
|
71 | See the appropriate installation page for details. | |
72 |
|
72 | |||
73 |
|
73 | |||
74 | 4. Install new version of Kallithea |
|
74 | 4. Install new version of Kallithea | |
75 | ----------------------------------- |
|
75 | ----------------------------------- | |
76 |
|
76 | |||
77 | Please refer to the instructions for the installation method you |
|
77 | Please refer to the instructions for the installation method you | |
78 | originally used to install Kallithea. |
|
78 | originally used to install Kallithea. | |
79 |
|
79 | |||
80 | If you originally installed using pip, it is as simple as:: |
|
80 | If you originally installed using pip, it is as simple as:: | |
81 |
|
81 | |||
82 | pip install --upgrade kallithea |
|
82 | pip install --upgrade kallithea | |
83 |
|
83 | |||
84 | If you originally installed from version control, it is as simple as:: |
|
84 | If you originally installed from version control, it is as simple as:: | |
85 |
|
85 | |||
86 | cd my-kallithea-clone |
|
86 | cd my-kallithea-clone | |
87 | hg pull -u |
|
87 | hg pull -u | |
88 | pip install -e . |
|
88 | pip install --upgrade -e . | |
89 |
|
89 | |||
90 |
|
90 | |||
91 | 5. Upgrade your configuration |
|
91 | 5. Upgrade your configuration | |
92 | ----------------------------- |
|
92 | ----------------------------- | |
93 |
|
93 | |||
94 | Run the following command to create a new configuration (``.ini``) file:: |
|
94 | Run the following command to create a new configuration (``.ini``) file:: | |
95 |
|
95 | |||
96 | gearbox make-config new.ini |
|
96 | gearbox make-config new.ini | |
97 |
|
97 | |||
98 | Then compare it with your old config file and see what changed. |
|
98 | Then compare it with your old config file and see what changed. | |
99 |
|
99 | |||
100 | .. note:: |
|
100 | .. note:: | |
101 | Please always make sure your ``.ini`` files are up to date. Errors |
|
101 | Please always make sure your ``.ini`` files are up to date. Errors | |
102 | can often be caused by missing parameters added in new versions. |
|
102 | can often be caused by missing parameters added in new versions. | |
103 |
|
103 | |||
104 | .. _upgrade_db: |
|
104 | .. _upgrade_db: | |
105 |
|
105 | |||
106 |
|
106 | |||
107 | 6. Upgrade your database |
|
107 | 6. Upgrade your database | |
108 | ------------------------ |
|
108 | ------------------------ | |
109 |
|
109 | |||
110 | .. note:: |
|
110 | .. note:: | |
111 | If you are *downgrading* Kallithea, you should perform the database |
|
111 | If you are *downgrading* Kallithea, you should perform the database | |
112 | migration step *before* installing the older version. (That is, |
|
112 | migration step *before* installing the older version. (That is, | |
113 | always perform migrations using the most recent of the two versions |
|
113 | always perform migrations using the most recent of the two versions | |
114 | you're migrating between.) |
|
114 | you're migrating between.) | |
115 |
|
115 | |||
116 | First, run the following command to see your current database version:: |
|
116 | First, run the following command to see your current database version:: | |
117 |
|
117 | |||
118 | alembic -c my.ini current |
|
118 | alembic -c my.ini current | |
119 |
|
119 | |||
120 | Typical output will be something like "9358dc3d6828 (head)", which is |
|
120 | Typical output will be something like "9358dc3d6828 (head)", which is | |
121 | the current Alembic database "revision ID". Write down the entire output |
|
121 | the current Alembic database "revision ID". Write down the entire output | |
122 | for troubleshooting purposes. |
|
122 | for troubleshooting purposes. | |
123 |
|
123 | |||
124 | The output will be empty if you're upgrading from Kallithea 0.3.x or |
|
124 | The output will be empty if you're upgrading from Kallithea 0.3.x or | |
125 | older. That's expected. If you get an error that the config file was not |
|
125 | older. That's expected. If you get an error that the config file was not | |
126 | found or has no ``[alembic]`` section, see the next section. |
|
126 | found or has no ``[alembic]`` section, see the next section. | |
127 |
|
127 | |||
128 | Next, if you are performing an *upgrade*: Run the following command to |
|
128 | Next, if you are performing an *upgrade*: Run the following command to | |
129 | upgrade your database to the current Kallithea version:: |
|
129 | upgrade your database to the current Kallithea version:: | |
130 |
|
130 | |||
131 | alembic -c my.ini upgrade head |
|
131 | alembic -c my.ini upgrade head | |
132 |
|
132 | |||
133 | If you are performing a *downgrade*: Run the following command to |
|
133 | If you are performing a *downgrade*: Run the following command to | |
134 | downgrade your database to the given version:: |
|
134 | downgrade your database to the given version:: | |
135 |
|
135 | |||
136 | alembic -c my.ini downgrade 0.4 |
|
136 | alembic -c my.ini downgrade 0.4 | |
137 |
|
137 | |||
138 | Alembic will show the necessary migrations (if any) as it executes them. |
|
138 | Alembic will show the necessary migrations (if any) as it executes them. | |
139 | If no "ERROR" is displayed, the command was successful. |
|
139 | If no "ERROR" is displayed, the command was successful. | |
140 |
|
140 | |||
141 | Should an error occur, the database may be "stranded" half-way |
|
141 | Should an error occur, the database may be "stranded" half-way | |
142 | through the migration, and you should restore it from backup. |
|
142 | through the migration, and you should restore it from backup. | |
143 |
|
143 | |||
144 | Enabling old Kallithea config files for Alembic use |
|
144 | Enabling old Kallithea config files for Alembic use | |
145 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
145 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
146 |
|
146 | |||
147 | Kallithea configuration files created before the introduction of Alembic |
|
147 | Kallithea configuration files created before the introduction of Alembic | |
148 | (i.e. predating Kallithea 0.4) need to be updated for use with Alembic. |
|
148 | (i.e. predating Kallithea 0.4) need to be updated for use with Alembic. | |
149 | Without this, Alembic will fail with an error like this:: |
|
149 | Without this, Alembic will fail with an error like this:: | |
150 |
|
150 | |||
151 | FAILED: No config file 'my.ini' found, or file has no '[alembic]' section |
|
151 | FAILED: No config file 'my.ini' found, or file has no '[alembic]' section | |
152 |
|
152 | |||
153 | If Alembic complains specifically about a missing ``alembic.ini``, it is |
|
153 | If Alembic complains specifically about a missing ``alembic.ini``, it is | |
154 | likely because you did not specify a config file using the ``-c`` option. |
|
154 | likely because you did not specify a config file using the ``-c`` option. | |
155 | On the other hand, if the mentioned config file actually exists, you |
|
155 | On the other hand, if the mentioned config file actually exists, you | |
156 | need to append the following lines to it:: |
|
156 | need to append the following lines to it:: | |
157 |
|
157 | |||
158 | [alembic] |
|
158 | [alembic] | |
159 | script_location = kallithea:alembic |
|
159 | script_location = kallithea:alembic | |
160 |
|
160 | |||
161 | Your config file should now work with Alembic. |
|
161 | Your config file should now work with Alembic. | |
162 |
|
162 | |||
163 |
|
163 | |||
164 | 7. Rebuild the Whoosh full-text index |
|
164 | 7. Rebuild the Whoosh full-text index | |
165 | ------------------------------------- |
|
165 | ------------------------------------- | |
166 |
|
166 | |||
167 | It is recommended that you rebuild the Whoosh index after upgrading since |
|
167 | It is recommended that you rebuild the Whoosh index after upgrading since | |
168 | new Whoosh versions can introduce incompatible index changes. |
|
168 | new Whoosh versions can introduce incompatible index changes. | |
169 |
|
169 | |||
170 |
|
170 | |||
171 | 8. Start the Kallithea web application |
|
171 | 8. Start the Kallithea web application | |
172 | -------------------------------------- |
|
172 | -------------------------------------- | |
173 |
|
173 | |||
174 | This step once again depends entirely on the web server software used to |
|
174 | This step once again depends entirely on the web server software used to | |
175 | serve Kallithea. |
|
175 | serve Kallithea. | |
176 |
|
176 | |||
177 | Before starting the new version of Kallithea, you may find it helpful to |
|
177 | Before starting the new version of Kallithea, you may find it helpful to | |
178 | clear out your log file so that new errors are readily apparent. |
|
178 | clear out your log file so that new errors are readily apparent. | |
179 |
|
179 | |||
180 | .. note:: |
|
180 | .. note:: | |
181 | If you're using Celery, make sure you restart all instances of it after |
|
181 | If you're using Celery, make sure you restart all instances of it after | |
182 | upgrade. |
|
182 | upgrade. | |
183 |
|
183 | |||
184 |
|
184 | |||
185 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
|
185 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv |
General Comments 0
You need to be logged in to leave comments.
Login now