.. _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 at Our Own Kallithea (aka OOK) on

https://kallithea-scm.org/repos/kallithea/ (which is our self-hosted instance

of Kallithea).

For now, we use Bitbucket_ for `Pull Requests`_ and `Issue Tracker`_ services. The

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

please use the `mailing list`_ 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.

Getting started

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

To get started with development::

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

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        python setup.py develop

        paster make-config Kallithea my.ini

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

        paster serve my.ini --reload &

        firefox http://127.0.0.1:5000/

You can also start out by forking https://bitbucket.org/conservancy/kallithea

on Bitbucket_ and create a local clone of your own fork.

Running tests

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

After finishing your changes make sure all tests pass cleanly. You can run

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

Contributions will be accepted in most formats - such as pull requests on

bitbucket, something hosted on your own Kallithea instance, or patches sent by

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

For now we just have one official branch ("default") and will keep it so stable

that it can be (and is) used in production. Experimental changes should live

elsewhere (for example in a pull request) until they are ready.

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

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

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