- Full text search powered by Whoosh on the source files, commit messages, and

  file names. Built-in indexing daemons, with optional incremental index build

  (no external search servers required all in one application).

- Setup project descriptions/tags and info inside built in DB for easy,

  non-filesystem operations.

- Intelligent cache with invalidation after push or project change, provides

  high performance and always up to date data.

- RSS/Atom feeds, Gravatar support, downloadable sources as zip/tar/gz.

- Optional async tasks for speed and performance using Celery_.

- Backup scripts can do backup of whole app and send it over scp to desired

  location.

- Based on TurboGears2, SQLAlchemy, Whoosh, Bootstrap, and other open source

  libraries.

- Uses PostgreSQL, SQLite, or MariaDB/MySQL databases.

License

-------

**Kallithea** is released under the GPLv3 license. Kallithea is a `Software

Freedom Conservancy`_ project and thus controlled by a non-profit organization.

No commercial entity can take ownership of the project and change the

direction.

Kallithea started out as an effort to make sure the existing GPLv3 codebase

would stay available under a legal license. Kallithea thus has to stay GPLv3

compatible ... but we are also happy it is GPLv3 and happy to keep it that way.

A different license (such as AGPL) could perhaps help attract a different

community with a different mix of Free Software people and companies but we are

happy with the current focus.

Community

---------

**Kallithea** is maintained by its users who contribute the fixes they would

like to see.

Get in touch with the rest of the community:

- Join the mailing list users and developers -- see

  http://lists.sfconservancy.org/mailman/listinfo/kallithea-general.

- Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use

  http://webchat.freenode.net/?channels=kallithea.

- Follow Kallithea on Twitter, **@KallitheaSCM**.

   .. note::

       Please try to read the documentation before posting any issues,

       especially the **troubleshooting section**

Online documentation

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

Online documentation for the current version of Kallithea is available at

https://docs.kallithea-scm.org/en/stable/. Documentation for the current development

version can be found on https://docs.kallithea-scm.org/en/default/.

You can also build the documentation locally: go to ``docs/`` and run::

   make html

.. note:: You need to have Sphinx_ installed to build the

          documentation. If you don't have Sphinx_ installed you can

          install it via the command: ``pip install sphinx`` .

Migrating from RhodeCode

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

Kallithea 0.3.2 and earlier supports migrating from an existing RhodeCode

installation. To migrate, 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 this version

of Kallithea.

.. _Python: http://www.python.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _Mercurial: http://mercurial.selenic.com/

.. _Bitbucket: http://bitbucket.org/

.. _GitHub: http://github.com/

.. _Subversion: http://subversion.tigris.org/

.. _Git: http://git-scm.com/

.. _Celery: http://celeryproject.org/

.. _Software Freedom Conservancy: http://sfconservancy.org/

.. _Puppet module: https://forge.puppetlabs.com/rauch/kallithea

.. _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.

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

        python3 -m venv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        pip install --upgrade -e . -r dev_requirements.txt python-ldap python-pam

        kallithea-cli config-create my.ini

        kallithea-cli db-create -c my.ini --user=user --email=user@example.com --password=password --repos=/tmp

        kallithea-cli front-end-build

        gearbox serve -c my.ini --reload &

        firefox http://127.0.0.1:5000/

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

.. _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 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.

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

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

A number of performance tests are present in the test suite, but they are

not run in a standard test run. These tests are useful to

evaluate the impact of certain code changes with respect to performance.

To run these tests::

    env TEST_PERFORMANCE=1 py.test kallithea/tests/performance

To analyze performance, you could install pytest-profiling_, which enables the

--profile and --profile-svg options to py.test.

.. _pytest-profiling: https://github.com/manahl/pytest-plugins/tree/master/pytest-profiling

.. _contributing-guidelines:

Contribution guidelines

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

Kallithea is GPLv3 and we assume all contributions are made by the

committer/contributor and under GPLv3 unless explicitly stated. We do care a

lot about preservation of copyright and license information for existing code

that is brought into the project.

email to the `kallithea-general`_ mailing list.

Make sure to test your changes both manually and with the automatic tests

before posting.

We care about quality and review and keeping a clean repository history. We

might give feedback that requests polishing contributions until they are

"perfect". We might also rebase and collapse and make minor adjustments to your

changes when we apply them.

We try to make sure we have consensus on the direction the project is taking.

Everything non-sensitive should be discussed in public -- preferably on the

mailing list.  We aim at having all non-trivial changes reviewed by at least

one other core developer before pushing. Obvious non-controversial changes will

be handled more casually.

There is a main development branch ("default") which is generally stable so that

it can be (and is) used in production. There is also a "stable" branch that is

almost exclusively reserved for bug fixes or trivial changes. Experimental

changes should live elsewhere (for example in a pull request) until they are

ready.

.. _coding-guidelines:

Coding guidelines

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

We don't have a formal coding/formatting standard. We are currently using a mix

of Mercurial's (https://www.mercurial-scm.org/wiki/CodingStyle), pep8, and

consistency with existing code. Run ``scripts/run-all-cleanup`` before

committing to ensure some basic code formatting consistency.

We support Python 3.6 and later.

We try to support the most common modern web browsers. IE9 is still supported

to the extent it is feasible, IE8 is not.

We primarily support Linux and OS X on the server side but Windows should also work.

HTML templates should use 2 spaces for indentation ... but be pragmatic. We

should use templates cleverly and avoid duplication. We should use reasonable

semantic markup with element classes and IDs that can be used for styling and testing.

We should only use inline styles in places where it really is semantic (such as

``display: none``).

JavaScript must use ``;`` between/after statements. Indentation 4 spaces. Inline

multiline functions should be indented two levels -- one for the ``()`` and one for

``{}``.

Variables holding jQuery objects should be named with a leading ``$``.

  been added to the session, and should not be added again.

* When getting an object from the session (via ``Session().query`` or

  any of the utility functions that look up objects in the database),

  it's already part of the session, and should not be added again.

  SQLAlchemy monitors attribute modifications automatically for all

  objects it knows about and syncs them to the database.

SQLAlchemy also flushes changes to the database automatically; manually

calling ``Session().flush`` is usually only necessary when the Python

code needs the database to assign an "auto-increment" primary key ID to

a freshly created model object (before flushing, the ID attribute will

be ``None``).

Debugging

^^^^^^^^^

A good way to trace what Kallithea is doing is to keep an eye on the output on

stdout/stderr of the server process. Perhaps change ``my.ini`` to log at

``DEBUG`` or ``INFO`` level, especially ``[logger_kallithea]``, but perhaps

also other loggers. It is often easier to add additional ``log`` or ``print``

statements than to use a Python debugger.

Sometimes it is simpler to disable ``errorpage.enabled`` and perhaps also

``trace_errors.enable`` to expose raw errors instead of adding extra

processing. Enabling ``debug`` can be helpful for showing and exploring

tracebacks in the browser, but is also insecure and will add extra processing.

TurboGears2 DebugBar

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

It is possible to enable the TurboGears2-provided DebugBar_, a toolbar overlayed

over the Kallithea web interface, allowing you to see:

* timing information of the current request, including profiling information

* request data, including GET data, POST data, cookies, headers and environment

  variables

* a list of executed database queries, including timing and result values

DebugBar is only activated when ``debug = true`` is set in the configuration

file. This is important, because the DebugBar toolbar will be visible for all

users, and allow them to see information they should not be allowed to see. Like

is anyway the case for ``debug = true``, do not use this in production!

To enable DebugBar, install ``tgext.debugbar`` and ``kajiki`` (typically via

``pip``) and restart Kallithea (in debug mode).

Thank you for your contribution!

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

.. _Weblate: http://weblate.org/

.. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general

.. _kallithea-general: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general

.. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/

.. _DebugBar: https://github.com/TurboGears/tgext.debugbar

.. _Quick Start: https://www.mercurial-scm.org/wiki/QuickStart

.. _Beginners Guide: https://www.mercurial-scm.org/wiki/BeginnersGuides

**Setup and configuration**

.. toctree::

   :maxdepth: 1

   setup

   administrator_guide/auth

   administrator_guide/vcs_setup

   usage/email

   usage/customization

**Maintenance**

.. toctree::

   :maxdepth: 1

   usage/backup

   usage/performance

   usage/debugging

   usage/troubleshooting

User guide

**********

.. toctree::

   :maxdepth: 1

   usage/general

   usage/vcs_notes

   usage/statistics

   api/api

Developer guide

***************

.. toctree::

   :maxdepth: 1

   contributing

   dev/i18n

   dev/dbmigrations

.. _python: http://www.python.org/

.. _django: http://www.djangoproject.com/

.. _mercurial: https://www.mercurial-scm.org/

.. _subversion: http://subversion.tigris.org/

.. _git: http://git-scm.com/

.. _celery: http://celeryproject.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _vcs: http://pypi.python.org/pypi/vcs