Changeset - 49be3b49c8e2
Parent rev.
Child rev.
[Not reviewed]
default
0 1 0
Karl Goetz - 8 years ago 2017-06-28 21:52:35
karl@kgoetz.id.au
docs/contributing: make contribution information more accessible

Try to make the contribution information more accessible to new users, by
giving a bit more detail about the different steps in making contributions.

Some rework of the original patch done by Thomas De Schampheleire:
- don't give the impression that Bitbucket is mandatory
- don't recommend creating feature branches for regular development
- reword/cross-reference section on contribution flow
1 file changed with 42 insertions and 3 deletions:
docs/contributing.rst
42
3
0 comments (0 inline, 0 general)
docs/contributing.rst
➞
Show inline comments
 
@@ -25,27 +25,60 @@ To register, you can use your Bitbucket
 
for more details.
 

			




	
	
	
		
 

			




	
	
	
		
 
Getting started

			




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

			




	
	
	
		
 

			




	
	
	
		
 
To get started with development::

			




	
	
	
		
 
To get started with Kallithea development::

			




	
	
	
		
 

			




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

			




	
	
	
		
 
        cd kallithea

			




	
	
	
		
 
        virtualenv ../kallithea-venv

			




	
	
	
		
 
        source ../kallithea-venv/bin/activate

			




	
	
	
		
 
        pip install --upgrade pip setuptools

			




	
	
	
		
 
        pip install -e .

			




	
	
	
		
 
        gearbox make-config my.ini

			




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

			




	
	
	
		
 
        gearbox serve -c 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.

			




	
	
	
		
 
If you plan to use Bitbucket_ for sending contributions, you can also fork

			




	
	
	
		
 
Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and

			




	
	
	
		
 
then replace the clone step above by a clone of your fork. In this case, please

			




	
	
	
		
 
see :ref:`contributing-guidelies` below for configuring your fork correctly.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
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

			




	
	
	
		
 
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. Install the test

			




	
	
		
 
@@ -111,12 +144,14 @@ To run these tests::

			




	
	
	
		
 

			




	
	
	
		
 
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

			




	
	
		
 
@@ -150,12 +185,14 @@ one other core developer before pushing.

			




	
	
	
		
 
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.

			




	
	
	
		
 

			




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

			




	
	
		
 
@@ -269,6 +306,8 @@ Thank you for your contribution!

			




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

			




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

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2025 by various authors & licensed under GPLv3.