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

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

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::

    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

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

which case it should be manually convinced it has to discard the commits it created by

using its administrative interface.

Manual creation of a new language translation

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

In the prepared development environment, run the following to ensure

all translation strings are extracted and up-to-date::

    python2 setup.py extract_messages

Create new language by executing following command::

    python2 setup.py init_catalog -l <new_language_code>

This creates a new translation under directory `kallithea/i18n/<new_language_code>`

based on the translation template file, `kallithea/i18n/kallithea.pot`.

Edit the new PO file located in `LC_MESSAGES` directory with poedit or your

favorite PO files editor. After you finished with the translations, check the

translation file for errors by executing::

    msgfmt -f -c kallithea/i18n/<new_language_code>/LC_MESSAGES/<updated_file.po>

Finally, compile the translations::

    python2 setup.py compile_catalog -l <new_language_code>

Updating translations

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

Extract the latest versions of strings for translation by running::

    python2 setup.py extract_messages

Update the PO file by doing::

    python2 setup.py update_catalog -l <new_language_code>

Edit the new updated translation file. Repeat all steps after `init_catalog` step from

new translation instructions

Testing translations

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

    py.test

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

import os

import re

import sys

import logging

import pkg_resources

import time

import formencode

from paste.deploy import loadwsgi

from routes.util import URLGenerator

import pytest

from pytest_localserver.http import WSGIServer

from kallithea.controllers.root import RootController

from kallithea.lib import inifile

from kallithea.lib.utils import repo2db_mapper

from kallithea.model.user import UserModel

from kallithea.model.meta import Session

from kallithea.model.db import Setting, User, UserIpMap

from kallithea.model.scm import ScmModel

from kallithea.tests.base import invalidate_all_caches, TEST_USER_REGULAR_LOGIN, TESTS_TMP_PATH, \

    TEST_USER_ADMIN_LOGIN, TEST_USER_ADMIN_PASS

import kallithea.tests.base # FIXME: needed for setting testapp instance!!!

from tg.util.webtest import test_context

def pytest_configure():

    os.environ['TZ'] = 'UTC'

    if not kallithea.is_windows:

        time.tzset() # only available on Unix

    path = os.getcwd()

    sys.path.insert(0, path)

    pkg_resources.working_set.add_entry(path)

    # Disable INFO logging of test database creation, restore with NOTSET

    logging.disable(logging.INFO)

    ini_settings = {

        '[server:main]': {

            'port': '4999',

        },

        '[app:main]': {

            'app_instance_uuid': 'test',

            'show_revision_number': 'true',

            'beaker.cache.sql_cache_short.expire': '1',

            'beaker.session.secret': '{74e0cd75-b339-478b-b129-07dd221def1f}',

        },

        '[handler_console]': {

            'formatter': 'color_formatter',

        },

        # The 'handler_console_sql' block is very similar to the one in

        # development.ini, but without the explicit 'level=DEBUG' setting:

        # it causes duplicate sqlalchemy debug logs, one through

        # handler_console_sql and another through another path.

        '[handler_console_sql]': {

            'formatter': 'color_formatter_sql',

        },

    }

    if os.environ.get('TEST_DB'):

        ini_settings['[app:main]']['sqlalchemy.url'] = os.environ.get('TEST_DB')

    test_ini_file = os.path.join(TESTS_TMP_PATH, 'test.ini')

    inifile.create(test_ini_file, None, ini_settings)

    context = loadwsgi.loadcontext(loadwsgi.APP, 'config:%s' % test_ini_file)

    from kallithea.tests.fixture import create_test_env, create_test_index

    # set KALLITHEA_NO_TMP_PATH=1 to disable re-creating the database and test repos

    if not int(os.environ.get('KALLITHEA_NO_TMP_PATH', 0)):

        create_test_env(TESTS_TMP_PATH, context.config())

    # set KALLITHEA_WHOOSH_TEST_DISABLE=1 to disable whoosh index during tests

    if not int(os.environ.get('KALLITHEA_WHOOSH_TEST_DISABLE', 0)):

        create_test_index(TESTS_TMP_PATH, context.config(), True)

    kallithea.tests.base.testapp = context.create()

    # do initial repo scan

    repo2db_mapper(ScmModel().repo_scan(TESTS_TMP_PATH))

    logging.disable(logging.NOTSET)

    kallithea.tests.base.url = URLGenerator(RootController().mapper, {'HTTP_HOST': 'example.com'})

    # set fixed language for form messages, regardless of environment settings

    formencode.api.set_stdtranslation(languages=[])

@pytest.fixture

def create_test_user():

    """Provide users that automatically disappear after test is over."""

    test_user_ids = []

    def _create_test_user(user_form):

        user = UserModel().create(user_form)

#!/usr/bin/env python2

"""

"""

import re

from kallithea.lib import inifile

# files to be generated from the mako template

ini_files = [

    ('development.ini',

        {

            '[server:main]': {

                'host': '0.0.0.0',

            },

            '[app:main]': {

                'debug': 'true',

                'app_instance_uuid': 'development-not-secret',

                'beaker.session.secret': 'development-not-secret',

            },

            '[handler_console]': {

                'formatter': 'color_formatter',

            },

            '[handler_console_sql]': {

                'formatter': 'color_formatter_sql',

            },

            '[logger_routes]': {

                'level': 'DEBUG',

            },

            '[logger_beaker]': {

                'level': 'DEBUG',

            },

            '[logger_templates]': {

                'level': 'INFO',

            },

            '[logger_kallithea]': {

                'level': 'DEBUG',

            },

            '[logger_tg]': {

                'level': 'DEBUG',

            },

            '[logger_gearbox]': {

                'level': 'DEBUG',

            },

            '[logger_whoosh_indexer]': {

                'level': 'DEBUG',

            },

        },

    ),

]