Blame doc/development.rst

Pierre-Yves Chibon 300c54
Development
Pierre-Yves Chibon 300c54
===========
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Get the sources
Pierre-Yves Chibon 300c54
---------------
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Anonymous:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 7013cc
  git clone https://pagure.io/pagure.git
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Contributors:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
  git clone ssh://git@pagure.io:pagure.git
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Dependencies
Pierre-Yves Chibon 300c54
------------
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
The dependencies of pagure are listed in the file ``requirements.txt``
Pierre-Yves Chibon 300c54
at the top level of the sources.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
.. note:: working in a `virtualenv <http: en="" latest="" www.virtualenv.org="">`_</http:>
Pierre-Yves Chibon 300c54
          is tricky due to the dependency on `pygit2 <http: www.pygit2.org="">`_</http:>
Pierre-Yves Chibon 300c54
          and thus on `libgit2 <https: libgit2.github.com="">`_</https:>
Pierre-Yves Chibon 300c54
          but the pygit2 `documentation has a solution for this
Pierre-Yves Chibon 300c54
          <http: install.html#libgit2-within-a-virtual-environment="" www.pygit2.org="">`_.</http:>
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Run pagure for development
Pierre-Yves Chibon d5796d
--------------------------
Pierre-Yves Chibon 300c54
Adjust the configuration file (secret key, database URL, admin group...)
Pierre-Yves Chibon 300c54
See :doc:`configuration` for more detailed information about the
Pierre-Yves Chibon 300c54
configuration.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Create the database scheme::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
  ./createdb
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Create the folder that will receive the different git repositories:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 4e55c5
    mkdir {repos,docs,forks,tickets,requests,remotes}
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Run the server:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
    ./runserver
Pierre-Yves Chibon 7013cc
Pierre-Yves Chibon 300c54
To get some profiling information you can also run it as:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
    ./runserver.py --profile
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
You should be able to access the server at http://localhost:5000
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Every time you save a file, the project will be automatically restarted
Pierre-Yves Chibon 300c54
so you can see your change immediatly.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Coding standards
Pierre-Yves Chibon 300c54
----------------
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
We are trying to make the code `PEP8-compliant
Pierre-Yves Chibon 300c54
<http: dev="" pep-0008="" peps="" www.python.org="">`_.  There is a `pep8 tool</http:>
Pierre-Yves Chibon 300c54
<http: pep8="" pypi="" pypi.python.org="">`_ that can automatically check</http:>
Pierre-Yves Chibon 300c54
your source.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
We are also inspecting the code using `pylint
Pierre-Yves Chibon 300c54
<http: pylint="" pypi="" pypi.python.org="">`_ and aim of course for a 10/10 code</http:>
Pierre-Yves Chibon 300c54
(but it is an assymptotic goal).
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
.. note:: both pep8 and pylint are available in Fedora via yum:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
          ::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
            yum install python-pep8 pylint
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Send patch
Pierre-Yves Chibon 300c54
----------
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
The easiest way to work on pagure is to make your own branch in git, make
Pierre-Yves Chibon 300c54
your changes to this branch, commit whenever you want, rebase on master,
Pierre-Yves Chibon 300c54
whenever you need and when you are done, send the patch either by email,
Pierre-Yves Chibon 300c54
via the trac or a pull-request (using git or github).
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
The workflow would therefore be something like:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
   git branch <my_shiny_feature></my_shiny_feature>
Pierre-Yves Chibon 300c54
   git checkout <my_shiny_feature></my_shiny_feature>
Pierre-Yves Chibon 300c54
   <work></work>
Pierre-Yves Chibon 300c54
   git commit file1 file2
Pierre-Yves Chibon 300c54
   <more work=""></more>
Pierre-Yves Chibon 300c54
   git commit file3 file4
Pierre-Yves Chibon 300c54
   git checkout master
Pierre-Yves Chibon 300c54
   git pull
Pierre-Yves Chibon 300c54
   git checkout <my_shiny_feature></my_shiny_feature>
Pierre-Yves Chibon 300c54
   git rebase master
Pierre-Yves Chibon 300c54
   git format-patch -2
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
This will create two patch files that you can send by email to submit in a ticket
Pierre-Yves Chibon 300c54
on pagure, by email or after forking the project on pagure by submitting a
Pierre-Yves Chibon 300c54
pull-request (in which case the last step above ``git format-patch -2`` is not
Pierre-Yves Chibon 300c54
needed.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Unit-tests
Pierre-Yves Chibon 300c54
----------
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pagure has a number of unit-tests.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
We aim at having a full (100%) coverage of the whole code (including the
Pierre-Yves Chibon 300c54
Flask application) and of course a smart coverage as in we want to check
Pierre-Yves Chibon 300c54
that the functions work the way we want but also that they fail when we
Pierre-Yves Chibon 300c54
expect it and the way we expect it.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Tests checking that function are failing when/how we want are as important
Pierre-Yves Chibon 300c54
as tests checking they work the way they are intended to.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
``runtests.sh``, located at the top of the sources, helps to run the
Pierre-Yves Chibon 300c54
unit-tests of the project with coverage information using `python-nose
Pierre-Yves Chibon 300c54
<https: nose.readthedocs.org="">`_.</https:>
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
.. note:: You can specify additional arguments to the nose command used
Pierre-Yves Chibon 300c54
          in this script by just passing arguments to the script.
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
          For example you can specify the ``-x`` / ``--stop`` argument:
Pierre-Yves Chibon 300c54
          `Stop running tests after the first error or failure` by just doing
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
          ::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
            ./runtests.sh --stop
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Each unit-tests files (located under ``tests/``) can be called
Pierre-Yves Chibon 300c54
by alone, allowing easier debugging of the tests. For example:
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
  python tests/test_pragure_lib.py
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
.. note:: In order to have coverage information you might have to install
Pierre-Yves Chibon 300c54
          ``python-coverage``
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
          ::
Pierre-Yves Chibon 300c54
Pierre-Yves Chibon 300c54
            yum install python-coverage