.. _contributing:

=========================

Contributing to Kallithea

=========================

Kallithea is developed and maintained by its users. Please join us and scratch

your own itch.

Infrastructure

--------------

The main repository is hosted on Our Own Kallithea (aka OOK) at

https://kallithea-scm.org/repos/kallithea/, our self-hosted instance

of Kallithea.

For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The

issue tracker is for tracking bugs, not for support, discussion, or ideas --

please use the `mailing list`_ or :ref:`IRC <readme>` to reach the community.

We use Weblate_ to translate the user interface messages into languages other

than English. Join our project on `Hosted Weblate`_ to help us.

To register, you can use your Bitbucket or GitHub account. See :ref:`translations`

for more details.

Getting started

---------------

To get started with Kallithea development::

        hg clone https://kallithea-scm.org/repos/kallithea

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        pip install --upgrade -e .

        pip install --upgrade -r dev_requirements.txt

        npm install     # install dependencies - both tools and data

        npm run less    # for generating css from less

        gearbox setup-db -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp

        gearbox serve -c my.ini --reload &

        firefox http://127.0.0.1:5000/

If you plan to use Bitbucket_ for sending contributions, you can also fork

Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and

then replace the clone step above by a clone of your fork. In this case, please

see :ref:`contributing-guidelines` below for configuring your fork correctly.

Contribution flow

-----------------

Starting from an existing Kallithea clone, make sure it is up to date with the

latest upstream changes::

        hg pull

        hg update

Review the :ref:`contributing-guidelines` and :ref:`coding-guidelines`.

If you are new to Mercurial, refer to Mercurial `Quick Start`_ and `Beginners

Guide`_ on the Mercurial wiki.

Now, make some changes and test them (see :ref:`contributing-tests`). Don't

forget to add new tests to cover new functionality or bug fixes.

For documentation changes, run ``make html`` from the ``docs`` directory to

generate the HTML result, then review them in your browser.

Before submitting any changes, run the cleanup script::

        ./scripts/run-all-cleanup

When you are completely ready, you can send your changes to the community for

review and inclusion. Most commonly used methods are sending patches to the

mailing list (via ``hg email``) or by creating a pull request on Bitbucket_.

.. _contributing-tests:

Running tests

-------------

After finishing your changes make sure all tests pass cleanly. Run the testsuite

by invoking ``py.test`` from the project root::

    py.test

Note that testing on Python 2.6 also requires ``unittest2``.

Note that on unix systems, the temporary directory (``/tmp`` or where

``$TMPDIR`` points) must allow executable files; Git hooks must be executable,

and the test suite creates repositories in the temporary directory. Linux

systems with /tmp mounted noexec will thus fail.

You can also use ``tox`` to run the tests with all supported Python versions

(currently Python 2.6--2.7).

When running tests, Kallithea generates a `test.ini` based on template values

in `kallithea/tests/conftest.py` and populates the SQLite database specified

there.

It is possible to avoid recreating the full test database on each invocation of

the tests, thus eliminating the initial delay. To achieve this, run the tests as::

    gearbox serve -c /tmp/kallithea-test-XXX/test.ini --pid-file=test.pid --daemon

    KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 py.test

    kill -9 $(cat test.pid)

In these commands, the following variables are used::

    KALLITHEA_WHOOSH_TEST_DISABLE=1 - skip whoosh index building and tests

    KALLITHEA_NO_TMP_PATH=1 - disable new temp path for tests, used mostly for testing_vcs_operations

You can run individual tests by specifying their path as argument to py.test.

py.test also has many more options, see `py.test -h`. Some useful options

are::

    -k EXPRESSION         only run tests which match the given substring

                          expression. An expression is a python evaluable

                          expression where all names are substring-matched

                          against test names and their parent classes. Example:

    -x, --exitfirst       exit instantly on first error or failed test.

    --lf                  rerun only the tests that failed at the last run (or

                          all if none failed)

    --ff                  run all tests but run the last failures first. This

                          may re-order tests and thus lead to repeated fixture

                          setup/teardown

    --pdb                 start the interactive Python debugger on errors.

    -s, --capture=no      don't capture stdout (any stdout output will be

                          printed immediately)

Performance tests

^^^^^^^^^^^^^^^^^

=======================

Database schema changes

=======================

Kallithea uses Alembic for :ref:`database migrations <upgrade_db>`

(upgrades and downgrades).

If you are developing a Kallithea feature that requires database schema

changes, you should make a matching Alembic database migration script:

1. :ref:`Create a Kallithea configuration and database <setup>` for testing

   the migration script, or use existing ``development.ini`` setup.

   Ensure that this database is up to date with the latest database

   schema *before* the changes you're currently developing. (Do not

   create the database while your new schema changes are applied.)

2. Create a separate throwaway configuration for iterating on the actual

   database changes::

   Edit the file to change database settings. SQLite is typically fine,

   but make sure to change the path to e.g. ``temp.db``, to avoid

   clobbering any existing database file.

3. Make your code changes (including database schema changes in ``db.py``).

4. After every database schema change, recreate the throwaway database

   to test the changes::

    rm temp.db

    gearbox setup-db -c temp.ini --repos=/var/repos --user=doe --email doe@example.com --password=123456 --no-public-access --force-yes

    gearbox repo-scan -c temp.ini

5. Once satisfied with the schema changes, auto-generate a draft Alembic

   script using the development database that has *not* been upgraded.

   (The generated script will upgrade the database to match the code.)

   ::

    alembic -c development.ini revision -m "area: add cool feature" --autogenerate

6. Edit the script to clean it up and fix any problems.

   Note that for changes that simply add columns, it may be appropriate

   to not remove them in the downgrade script (and instead do nothing),

   to avoid the loss of data. Unknown columns will simply be ignored by

   Kallithea versions predating your changes.

7. Run ``alembic -c development.ini upgrade head`` to apply changes to

   the (non-throwaway) database, and test the upgrade script. Also test

   downgrades.

   The included ``development.ini`` has full SQL logging enabled. If

   you're using another configuration file, you may want to enable it

   by setting ``level = DEBUG`` in section ``[handler_console_sql]``.

The Alembic migration script should be committed in the same revision as

the database schema (``db.py``) changes.

See the `Alembic documentation`__ for more information, in particular

the tutorial and the section about auto-generating migration scripts.

.. __: http://alembic.zzzcomputing.com/en/latest/

Troubleshooting

---------------

* If ``alembic --autogenerate`` responds "Target database is not up to

  date", you need to either first use Alembic to upgrade the database

  to the most recent version (before your changes), or recreate the

  database from scratch (without your schema changes applied).

- Right-click on get-pip.py and choose Saves as...

- Run "python2 get-pip.py" in the folder where you downloaded get-pip.py (may require admin access).

.. note::

   See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows

   for details and alternative methods.

Note that pip.exe will be placed inside your Python installation's

Scripts folder, which is likely not on your path. To correct this,

open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]\Scripts" /M

Step 5 -- Kallithea folder structure

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a Kallithea folder structure.

This is only an example to install Kallithea. Of course, you can

change it. However, this guide will follow the proposed structure, so

please later adapt the paths if you change them. Folders without

spaces are recommended.

Create the following folder structure::

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

   A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.

   It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa.

In a command prompt type::

  pip install virtualenv

Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).

To create a virtual environment, run::

  virtualenv C:\Kallithea\Env

Step 7 -- Install Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies.

Some Python packages use managed code and need to be compiled.

This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.

Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27

.. note::

  You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler.

In a command prompt type (adapting paths if necessary)::

  cd C:\Kallithea\Env\Scripts

  activate

  pip install --upgrade pip setuptools

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

  pip install kallithea

.. note:: This will take some time. Please wait patiently until it is fully

          complete. Some warnings will appear. Don't worry, they are

          normal.

Step 8 -- Install Git (optional)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Mercurial being a python package, was installed automatically when doing ``pip install kallithea``.

You need to install Git manually if you want Kallithea to be able to host Git repositories.

See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.

The location of the Git binaries (like ``c:\path\to\git\bin``) must be

added to the ``PATH`` environment variable so ``git.exe`` and other tools like

``gzip.exe`` are available.

Step 9 -- Configuring Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Steps taken from `<setup.html>`_

You have to use the same command prompt as in Step 7, so if you closed

it, reopen it following the same commands (including the "activate"

one). When ready, type::

  cd C:\Kallithea\Bin

Then you must edit my.ini to fit your needs (IP address, IP

port, mail settings, database, etc.). `NotePad++`__ or a similar text

editor is recommended to properly handle the newline character

differences between Unix and Windows.

__ http://notepad-plus-plus.org/

For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::

  gearbox setup-db -c my.ini

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a new database, answer yes (y)

The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).

The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).

If you make a mistake and the script doesn't end, don't worry: start it again.

If you decided not to install Git, you will get errors about it that you can ignore.

Step 10 -- Running Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::

  gearbox serve -c my.ini

Open your web server, and go to http://127.0.0.1:5000

It works!! :-)

Remark:

If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer.

What this guide does not cover:

- Installing Celery

- Running Kallithea as a Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

  Close CMD (the path variable will be updated then)

- Using support tools on WINDOWS Vista/7:

  Open a CMD and type::

    SETX PATH "%PATH%;[your-python-path]" /M

  Please substitute [your-python-path] with your Python installation path.

  Typically: C:\\Python27

Step 5 -- Kallithea folder structure

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create a Kallithea folder structure

This is only a example to install Kallithea, you can of course change

it. However, this guide will follow the proposed structure, so please

later adapt the paths if you change them. My recommendation is to use

folders with NO SPACES. But you can try if you are brave...

Create the following folder structure::

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Install Virtual Env for Python

Navigate to: http://www.virtualenv.org/en/latest/index.html#installation

Right click on "virtualenv.py" file and choose "Save link as...".

Download to C:\\Kallithea (or whatever you want)

(the file is located at

https://raw.github.com/pypa/virtualenv/master/virtualenv.py)

Create a virtual Python environment in C:\\Kallithea\\Env (or similar). To

do so, open a CMD (Python Path should be included in Step3), navigate

where you downloaded "virtualenv.py", and write::

  python2 virtualenv.py C:\Kallithea\Env

(--no-site-packages is now the default behaviour of virtualenv, no need

to include it)

Step 7 -- Install Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

Finally, install Kallithea

Close previously opened command prompt/s, and open a Visual Studio 2008

Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open

"Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->

"Visual Studio 2008 Command Prompt"

.. note::

   64-bit: For 64-bit you need to modify the shortcut that is used to start the

   Visual Studio 2008 Command Prompt. Use right-mouse click to open properties.

Change commandline from::

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86

to::

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64

In that CMD (loaded with VS2008 PATHs) type::

  cd C:\Kallithea\Env\Scripts (or similar)

  activate

  pip install --upgrade pip setuptools

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

 pip install kallithea

(long step, please wait until fully complete)

Some warnings will appear, don't worry as they are normal.

Step 8 -- Configuring Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

steps taken from http://packages.python.org/Kallithea/setup.html

You have to use the same Visual Studio 2008 command prompt as Step7, so

if you closed it reopen it following the same commands (including the

"activate" one). When ready, just type::

  cd C:\Kallithea\Bin

Then, you must edit my.ini to fit your needs (network address and

port, mail settings, database, whatever). I recommend using NotePad++

(free) or similar text editor, as it handles well the EndOfLine

character differences between Unix and Windows

(http://notepad-plus-plus.org/)

For the sake of simplicity lets run it with the default settings. After

your edits (if any), in the previous Command Prompt, type::

 gearbox setup-db -c my.ini

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a NEW database,

answer yes (y)

The script will ask you for repository path, answer C:\\Kallithea\\Repos

(or similar)

The script will ask you for admin username and password, answer "admin"

+ "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or

whatever you want)

If you make some mistake and the script does not end, don't worry, start

it again.

Step 9 -- Running Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the previous command prompt, being in the C:\\Kallithea\\Bin folder,

just type::

 gearbox serve -c my.ini

Open yout web server, and go to http://127.0.0.1:5000

It works!! :-)

Remark:

If it does not work first time, just Ctrl-C the CMD process and start it

again. Don't forget the "http://" in Internet Explorer

What this Guide does not cover:

- Installing Celery

- Running Kallithea as Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

.. _setup:

=====

Setup

=====

Preparing front-end

-------------------

Temporarily, in the current Kallithea version, some extra steps are required to

build front-end files:

Find the right ``kallithea/public/less`` path with::

    python -c "import os, kallithea; print os.path.join(os.path.dirname(os.path.abspath(kallithea.__file__)), 'public', 'less')"

Then run::

    npm install

    npm run less

Setting up Kallithea

--------------------

First, you will need to create a Kallithea configuration file. Run the

following command to do so::

This will create the file ``my.ini`` in the current directory. This

configuration file contains the various settings for Kallithea, e.g.

proxy port, email settings, usage of static files, cache, Celery

settings, and logging. Extra settings can be specified like::

Next, you need to create the databases used by Kallithea. It is recommended to

use PostgreSQL or SQLite (default). If you choose a database other than the

default, ensure you properly adjust the database URL in your ``my.ini``

configuration file to use this other database. Kallithea currently supports

PostgreSQL, SQLite and MySQL databases. Create the database by running

the following command::

    gearbox setup-db -c my.ini

This will prompt you for a "root" path. This "root" path is the location where

Kallithea will store all of its repositories on the current machine. After

entering this "root" path ``setup-db`` will also prompt you for a username

and password for the initial admin account which ``setup-db`` sets

up for you.

The ``setup-db`` values can also be given on the command line.

Example::

    gearbox setup-db -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos

The ``setup-db`` command will create all needed tables and an

admin account. When choosing a root path you can either use a new

empty location, or a location which already contains existing

repositories. If you choose a location which contains existing

repositories Kallithea will add all of the repositories at the chosen

location to its database.  (Note: make sure you specify the correct

path to the root).

.. note:: the given path for Mercurial_ repositories **must** be write

          accessible for the application. It's very important since

          the Kallithea web interface will work without write access,

          but when trying to do a push it will fail with permission

          denied errors unless it has write access.

You are now ready to use Kallithea. To run it simply execute::

    gearbox serve -c my.ini

- This command runs the Kallithea server. The web app should be available at

  http://127.0.0.1:5000. The IP address and port is configurable via the

  configuration file created in the previous step.

- Log in to Kallithea using the admin account created when running ``setup-db``.

- The default permissions on each repository is read, and the owner is admin.

  Remember to update these if needed.

- In the admin panel you can toggle LDAP, anonymous, and permissions

  settings, as well as edit more advanced options on users and

  repositories.

Internationalization (i18n support)

-----------------------------------

The Kallithea web interface is automatically displayed in the user's preferred

language, as indicated by the browser. Thus, different users may see the

application in different languages. If the requested language is not available

(because the translation file for that language does not yet exist or is

incomplete), the language specified in setting ``i18n.lang`` in the Kallithea

configuration file is used as fallback. If no fallback language is explicitly

specified, English is used.

If you want to disable automatic language detection and instead configure a

fixed language regardless of user preference, set ``i18n.enabled = false`` and

set ``i18n.lang`` to the desired language (or leave empty for English).

Using Kallithea with SSH

------------------------

Kallithea currently only hosts repositories using http and https. (The addition

of ssh hosting is a planned future feature.) However you can easily use ssh in

parallel with Kallithea. (Repository access via ssh is a standard "out of

the box" feature of Mercurial_ and you can use this to access any of the

repositories that Kallithea is hosting. See PublishingRepositories_)

Kallithea repository structures are kept in directories with the same name

as the project. When using repository groups, each group is a subdirectory.

This allows you to easily use ssh for accessing repositories.

In order to use ssh you need to make sure that your web server and the users'

login accounts have the correct permissions set on the appropriate directories.

.. note:: These permissions are independent of any permissions you

          have set up using the Kallithea web interface.

If your main directory (the same as set in Kallithea settings) is for

example set to ``/srv/repos`` and the repository you are using is

named ``kallithea``, then to clone via ssh you should run::

    hg clone ssh://user@kallithea.example.com/srv/repos/kallithea

Using other external tools such as mercurial-server_ or using ssh key-based

authentication is fully supported.

.. note:: In an advanced setup, in order for your ssh access to use

          the same permissions as set up via the Kallithea web

    install Kallithea 0.3.2 and follow the instructions in the 0.3.2

    README to perform a one-time conversion of the database from

    RhodeCode to Kallithea, before upgrading to the latest version

    of Kallithea.

1. Stop the Kallithea web application

-------------------------------------

This step depends entirely on the web server software used to serve

Kallithea, but in any case, Kallithea should not be running during

the upgrade.

.. note::

    If you're using Celery, make sure you stop all instances during the

    upgrade.

2. Create a backup of both database and configuration

-----------------------------------------------------

You are of course strongly recommended to make backups regularly, but it

is *especially* important to make a full database and configuration

backup before performing a Kallithea upgrade.

Back up your configuration

^^^^^^^^^^^^^^^^^^^^^^^^^^

Make a copy of your Kallithea configuration (``.ini``) file.

If you are using :ref:`rcextensions <customization>`, you should also

make a copy of the entire ``rcextensions`` directory.

Back up your database

^^^^^^^^^^^^^^^^^^^^^

If using SQLite, simply make a copy of the Kallithea database (``.db``)

file.

If using PostgreSQL, please consult the documentation for the ``pg_dump``

utility.

If using MySQL, please consult the documentation for the ``mysqldump``

utility.

Look for ``sqlalchemy.url`` in your configuration file to determine

database type, settings, location, etc.

3. Activate the Kallithea virtual environment (if any)

------------------------------------------------------

Verify that you are using the Python environment that you originally

installed Kallithea in by running::

    pip freeze

This will list all packages installed in the current environment. If

Kallithea isn't listed, activate the correct virtual environment.

See the appropriate installation page for details.

4. Install new version of Kallithea

-----------------------------------

Please refer to the instructions for the installation method you

originally used to install Kallithea.

If you originally installed using pip, it is as simple as::

    pip install --upgrade kallithea

If you originally installed from version control, it is as simple as::

    cd my-kallithea-clone

    hg pull -u

    pip install --upgrade -e .

Temporarily, in the current version, an extra step is required to build

front-end files:

Find the right ``kallithea/public/less`` path with::

    python -c "import os, kallithea; print os.path.join(os.path.dirname(os.path.abspath(kallithea.__file__)), 'public', 'less')"

Then run::

    npm install

    npm run less

5. Upgrade your configuration

-----------------------------

Run the following command to create a new configuration (``.ini``) file::

Then compare it with your old config file and see what changed.

.. note::

    Please always make sure your ``.ini`` files are up to date. Errors

    can often be caused by missing parameters added in new versions.

.. _upgrade_db:

6. Upgrade your database

------------------------

.. note::

    If you are *downgrading* Kallithea, you should perform the database

    migration step *before* installing the older version. (That is,

    always perform migrations using the most recent of the two versions

    you're migrating between.)

First, run the following command to see your current database version::

    alembic -c my.ini current

Typical output will be something like "9358dc3d6828 (head)", which is

the current Alembic database "revision ID". Write down the entire output

for troubleshooting purposes.

The output will be empty if you're upgrading from Kallithea 0.3.x or

older. That's expected. If you get an error that the config file was not

found or has no ``[alembic]`` section, see the next section.

Next, if you are performing an *upgrade*: Run the following command to

upgrade your database to the current Kallithea version::

    alembic -c my.ini upgrade head

If you are performing a *downgrade*: Run the following command to

downgrade your database to the given version::

    alembic -c my.ini downgrade 0.4

Alembic will show the necessary migrations (if any) as it executes them.

If no "ERROR" is displayed, the command was successful.

Should an error occur, the database may be "stranded" half-way

through the migration, and you should restore it from backup.

Enabling old Kallithea config files for Alembic use

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Kallithea configuration files created before the introduction of Alembic

(i.e. predating Kallithea 0.4) need to be updated for use with Alembic.

Without this, Alembic will fail with an error like this::

    FAILED: No config file 'my.ini' found, or file has no '[alembic]' section

If Alembic complains specifically about a missing ``alembic.ini``, it is

likely because you did not specify a config file using the ``-c`` option.

On the other hand, if the mentioned config file actually exists, you

need to append the following lines to it::

    [alembic]

    script_location = kallithea:alembic

Your config file should now work with Alembic.

7. Update Git repository hooks

------------------------------

It is possible that an upgrade involves changes to the Git hooks installed by

Kallithea. As these hooks are created inside the repositories on the server

filesystem, they are not updated automatically when upgrading Kallithea itself.

To update the hooks of your Git repositories:

* Go to *Admin > Settings > Remap and Rescan*

* Select the checkbox *Install Git hooks*

* Click the button *Rescan repositories*

.. note::

    Kallithea does not use hooks on Mercurial repositories. This step is thus

    not necessary if you only have Mercurial repositories.

8. Rebuild the Whoosh full-text index

-------------------------------------

It is recommended that you rebuild the Whoosh index after upgrading since

new Whoosh versions can introduce incompatible index changes.

9. Start the Kallithea web application

--------------------------------------

This step once again depends entirely on the web server software used to