diff --git a/docs/contributing.rst b/docs/contributing.rst --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -11,13 +11,13 @@ 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). +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 Tracker`_ services. The -issue tracker is for tracking bugs, not for support, discussion, or ideas - -please use the `mailing list`_ to reach the community. +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 ` 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. @@ -48,7 +48,7 @@ Running tests After finishing your changes make sure all tests pass cleanly. You can run the testsuite running ``nosetests`` from the project root, or if you use tox -run ``tox`` for python2.6-2.7 with multiple database test. +run ``tox`` for Python 2.6--2.7 with multiple database test. When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the SQLite database specified there. @@ -90,22 +90,23 @@ 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 +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 classes and ids that can be used for styling and testing. +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). +``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 -{}. jQuery value arrays should have a leading $. +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 ``$``. Commit messages should have a leading short line summarizing the changes. For -bug fixes, put "(Issue #123)" at the end of this line. +bug fixes, put ``(Issue #123)`` at the end of this line. -Contributions will be accepted in most formats - such as pull requests on +Contributions will be accepted in most formats -- such as pull requests on bitbucket, something hosted on your own Kallithea instance, or patches sent by -email to the kallithea-general mailing list. +email to the `kallithea-general`_ mailing list. Make sure to test your changes both manually and with the automatic tests before posting. @@ -116,7 +117,7 @@ might give feedback that requests polish 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 +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. @@ -132,7 +133,7 @@ elsewhere (for example in a pull request --------- 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 +wiki_ for some ideas of places we might want to go -- contributions in these areas are very welcome. @@ -141,9 +142,10 @@ 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 +.. _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