Commit e66e79d Merge #3609 `Update the documentation`

3 files Merged and Committed by ryanlerch 5 days ago
 1 @@ -75,6 +75,21 @@
 2       if you want Pagure to provide valid URLs in the UI for git repositories, you
 3       will need to adjust Pagure's configuration found in ~/pagure.cfg on the guest.
 4   
 5 + When the vagrant VM is up and running, connect to it with::
 6 + 
 7 +     $ vagrant ssh
 8 + 
 9 + This will log you into the VM as the user ``vagrant`` which has a couple of aliases
10 + preconfigured::
11 + 
12 +     $ pstart            # Starts pagure, the workers and other tasks
13 +     $ pstop             # Stops all those tasks again
14 +     $ pstatus           # Shows pagure status
15 + 
16 + The Vagrant pagure doesn't have its own log file, use ``journalctl -f`` to 
17 + show the pagure output. The verbosity can be configured in the pagure config file
18 + with the ``LOGGING`` parameter. 
19 + 
20   Docker Compose
21   ^^^^^^^^^^^^^^
22   Create the folder that will receive the projects, forks, docs, requests and
1 @@ -5,7 +5,7 @@
2   
3   - Check that your python code is `PEP8-compliant
4     <http://www.python.org/dev/peps/pep-0008/>`_.  There is a `flake8 tool
5 -   <http://pypi.python.org/pypi/flake8>`_ that automatically check the sources as
6 +   <http://pypi.python.org/pypi/flake8>`_ that automatically checks the sources as
7     part of the tests.
8   
9   - We run the source code through `black <https://pypi.python.org/pypi/black>`_
 1 @@ -45,6 +45,14 @@
 2             but the pygit2 `documentation has a solution for this
 3             <http://www.pygit2.org/install.html#libgit2-within-a-virtual-environment>`_.
 4   
 5 + How to run pagure
 6 + -----------------
 7 + 
 8 + There are several options when it comes to a development environment. Vagrant
 9 + will provide you with a virtual machine which you can develop on, you can use
10 + a container to run pagure or you can install it directly on your host machine.
11 + The README has detailed instructions for the different options.
12 + 
13   
14   Run pagure for development
15   --------------------------
16 @@ -183,26 +191,25 @@
17   ----------------
18   
19   We are trying to make the code `PEP8-compliant
20 - <http://www.python.org/dev/peps/pep-0008/>`_.  There is a `pep8 tool
21 - <http://pypi.python.org/pypi/pep8>`_ that can automatically check
22 + <http://www.python.org/dev/peps/pep-0008/>`_.  There is a `flake8 tool
23 + <http://pypi.python.org/pypi/flake8>`_ that can automatically check
24   your source.
25   
26 + We run the source code through `black <https://pypi.python.org/pypi/black>`_
27 + as part of the tests, so you may have to do some adjustments or run it
28 + yourself (which is simple: ``black /path/to/pagure``).
29   
30 - We are also inspecting the code using `pylint
31 - <http://pypi.python.org/pypi/pylint>`_ and aim of course for a 10/10 code
32 - (but it is an asymptotic goal).
33 - 
34 - .. note:: both pep8 and pylint are available in Fedora:
35 + .. note:: flake8 and black are available in Fedora:
36   
37             ::
38   
39 -             dnf install python-pep8 pylint
40 +             dnf install python3-flake8 python3-black
41   
42             or
43   
44             ::
45   
46 -             yum install python-pep8 pylint
47 +             yum install python3-flake8 python3-black
48   
49   
50   Send patch
51 @@ -235,6 +242,19 @@
52   pull-request (in which case the last step above ``git format-patch -2`` is not
53   needed.
54   
55 + .. note:: Though not required, it’s a good idea to begin the commit message 
56 +           with a single short (less than 50 character) line summarizing the 
57 +           change, followed by a blank line and then a more thorough description. 
58 +           The text up to the first blank line in a commit message is treated 
59 +           as the commit title, and that title is used throughout Git. 
60 +           For example, git-format-patch turns a commit into email, and it 
61 +           uses the title on the Subject line and the rest of the commit in 
62 +           the body.
63 +           Pagure uses lines that contain only 'Fixes #number' as references
64 +           to issues. If for example a commit message of a pagure patch has 
65 +           a line 'Fixes #3547' and a pullrequest (PR) gets created in pagure, 
66 +           this PR will be linked to from ``https://pagure.io/pagure/issue/3547``
67 + 
68   
69   Unit-tests
70   ----------
71 @@ -253,7 +273,7 @@
72   
73   
74   So here are a few steps that one could perform to run unit-tests in a
75 - local pagure instance.
76 + local pagure instance. 
77   
78   * Install the dependencies::
79   
80 @@ -318,3 +338,14 @@
81             ::
82   
83               yum install python-coverage
84 + 
85 + To run the unit-tests, there is also a container available with all the dependencies needed.
86 + Use the following command to run the tests ::
87 + 
88 +     $ ./dev/run-tests-docker.py
89 + 
90 + This command will build a fedora based container and execute the test suite. You can also
91 + limit the tests to unit-test files or single tests similar to the ``./runtests.sh`` 
92 + options described above.
93 + 
94 +