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

``{}``.

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

Commit messages should have a leading short line summarizing the changes. For

bug fixes, put ``(Issue #123)`` at the end of this line.

Use American English grammar and spelling overall. Use `English title case`_ for

page titles, button labels, headers, and 'labels' for fields in forms.

.. _English title case: https://en.wikipedia.org/wiki/Capitalization#Title_case

Template helpers (that is, everything in ``kallithea.lib.helpers``)

should only be referenced from templates. If you need to call a

helper from the Python code, consider moving the function somewhere

else (e.g. to the model).

Notes on the SQLAlchemy session

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

Each HTTP request runs inside an independent SQLAlchemy session (as well

as in an independent database transaction). Database model objects

(almost) always belong to a particular SQLAlchemy session, which means

that SQLAlchemy will ensure that they're kept in sync with the database

(but also means that they cannot be shared across requests).

Objects can be added to the session using ``Session().add``, but this is

rarely needed:

* When creating a database object by calling the constructor directly,

  it must explicitly be added to the session.

* When creating an object using a factory function (like

  ``create_repo``), the returned object has already (by convention)

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

"Roadmap"

---------

We do not have a road map but are waiting for your contributions. Refer to the

wiki_ for some ideas of places we might want to go -- contributions in these

areas are very welcome.

Thank you for your contribution!

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

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

.. _issue tracking: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open

.. _pull requests: https://bitbucket.org/conservancy/kallithea/pull-requests

.. _bitbucket: http://bitbucket.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/

.. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home

    # gearbox options are loaded and merged into the configuration. Then an

    # after_init_config(conf) method of AppConfig is called for any change that

    # might depend on options provided by configuration files.

    def __init__(self):

        super(KallitheaAppConfig, self).__init__()

        self['package'] = kallithea

        self['prefer_toscawidgets2'] = False

        self['use_toscawidgets'] = False

        self['renderers'] = []

        # Enable json in expose

        self['renderers'].append('json')

        # Configure template rendering

        self['renderers'].append('mako')

        self['default_renderer'] = 'mako'

        self['use_dotted_templatenames'] = False

        # Configure Sessions, store data as JSON to avoid pickle security issues

        self['session.enabled'] = True

        self['session.data_serializer'] = 'json'

        # Configure the base SQLALchemy Setup

        self['use_sqlalchemy'] = True

        self['model'] = kallithea.model.base

        self['DBSession'] = kallithea.model.meta.Session

        # Configure App without an authentication backend.

        self['auth_backend'] = None

        # Use custom error page for these errors. By default, Turbogears2 does not add

        # 400 in this list.

        # Explicitly listing all is considered more robust than appending to defaults,

        # in light of possible future framework changes.

        self['errorpage.status_codes'] = [400, 401, 403, 404]

        # Disable transaction manager -- currently Kallithea takes care of transactions itself

        self['tm.enabled'] = False

base_config = KallitheaAppConfig()

# TODO still needed as long as we use pylonslib

sys.modules['pylons'] = tg

def setup_configuration(app):

    config = app.config

    # store some globals into kallithea

    kallithea.CELERY_ON = str2bool(config['app_conf'].get('use_celery'))

    kallithea.CELERY_EAGER = str2bool(config['app_conf'].get('celery.always.eager'))

    kallithea.CONFIG = config

    # Provide routes mapper to the RoutedController

    root_controller = app.find_controller('root')

    root_controller.mapper = config['routes.map'] = make_map(config)

    load_rcextensions(root_path=config['here'])

    # FIXME move test setup code out of here

    test = os.path.split(config['__file__'])[-1] == 'test.ini'

    if test:

        test_env = not int(os.environ.get('KALLITHEA_NO_TMP_PATH', 0))

        test_index = not int(os.environ.get('KALLITHEA_WHOOSH_TEST_DISABLE', 0))

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

            # swap config if we pass environment variable

            config['sqlalchemy.url'] = os.environ.get('TEST_DB')

        from kallithea.tests.fixture import create_test_env, create_test_index

        from kallithea.tests.base import TESTS_TMP_PATH

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

        #test repos

        if test_env:

            create_test_env(TESTS_TMP_PATH, config)

        #set KALLITHEA_WHOOSH_TEST_DISABLE=1 to disable whoosh index during tests

        if test_index:

            create_test_index(TESTS_TMP_PATH, config, True)

    set_available_permissions(config)

    repos_path = make_ui('db').configitems('paths')[0][1]

    config['base_path'] = repos_path

    set_app_settings(config)

    instance_id = kallithea.CONFIG.get('instance_id', '*')

    if instance_id == '*':

        instance_id = '%s-%s' % (platform.uname()[1], os.getpid())

        kallithea.CONFIG['instance_id'] = instance_id

    # update kallithea.CONFIG with the meanwhile changed 'config'

    kallithea.CONFIG.update(config)

    # configure vcs and indexer libraries (they are supposed to be independent

    # as much as possible and thus avoid importing tg.config or