From e66e79d7e5e3208608d5e225d078426378937842 Mon Sep 17 00:00:00 2001 From: Ryan Lerch Date: Sep 13 2018 03:20:57 +0000 Subject: Merge #3609 `Update the documentation` --- diff --git a/README.rst b/README.rst index 6f7c8d1..464e9af 100644 --- a/README.rst +++ b/README.rst @@ -75,6 +75,21 @@ host machine. if you want Pagure to provide valid URLs in the UI for git repositories, you will need to adjust Pagure's configuration found in ~/pagure.cfg on the guest. +When the vagrant VM is up and running, connect to it with:: + + $ vagrant ssh + +This will log you into the VM as the user ``vagrant`` which has a couple of aliases +preconfigured:: + + $ pstart # Starts pagure, the workers and other tasks + $ pstop # Stops all those tasks again + $ pstatus # Shows pagure status + +The Vagrant pagure doesn't have its own log file, use ``journalctl -f`` to +show the pagure output. The verbosity can be configured in the pagure config file +with the ``LOGGING`` parameter. + Docker Compose ^^^^^^^^^^^^^^ Create the folder that will receive the projects, forks, docs, requests and diff --git a/doc/contributing.rst b/doc/contributing.rst index 7367f4c..bd54af5 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -5,7 +5,7 @@ If you're submitting patches to pagure, please observe the following: - Check that your python code is `PEP8-compliant `_. There is a `flake8 tool - `_ that automatically check the sources as + `_ that automatically checks the sources as part of the tests. - We run the source code through `black `_ diff --git a/doc/development.rst b/doc/development.rst index c3ba75c..893495c 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -45,6 +45,14 @@ at the top level of the sources. but the pygit2 `documentation has a solution for this `_. +How to run pagure +----------------- + +There are several options when it comes to a development environment. Vagrant +will provide you with a virtual machine which you can develop on, you can use +a container to run pagure or you can install it directly on your host machine. +The README has detailed instructions for the different options. + Run pagure for development -------------------------- @@ -183,26 +191,25 @@ Coding standards ---------------- We are trying to make the code `PEP8-compliant -`_. There is a `pep8 tool -`_ that can automatically check +`_. There is a `flake8 tool +`_ that can automatically check your source. +We run the source code through `black `_ +as part of the tests, so you may have to do some adjustments or run it +yourself (which is simple: ``black /path/to/pagure``). -We are also inspecting the code using `pylint -`_ and aim of course for a 10/10 code -(but it is an asymptotic goal). - -.. note:: both pep8 and pylint are available in Fedora: +.. note:: flake8 and black are available in Fedora: :: - dnf install python-pep8 pylint + dnf install python3-flake8 python3-black or :: - yum install python-pep8 pylint + yum install python3-flake8 python3-black Send patch @@ -235,6 +242,19 @@ on pagure, by email or after forking the project on pagure by submitting a pull-request (in which case the last step above ``git format-patch -2`` is not needed. +.. note:: Though not required, it’s a good idea to begin the commit message + with a single short (less than 50 character) line summarizing the + change, followed by a blank line and then a more thorough description. + The text up to the first blank line in a commit message is treated + as the commit title, and that title is used throughout Git. + For example, git-format-patch turns a commit into email, and it + uses the title on the Subject line and the rest of the commit in + the body. + Pagure uses lines that contain only 'Fixes #number' as references + to issues. If for example a commit message of a pagure patch has + a line 'Fixes #3547' and a pullrequest (PR) gets created in pagure, + this PR will be linked to from ``https://pagure.io/pagure/issue/3547`` + Unit-tests ---------- @@ -253,7 +273,7 @@ as tests checking they work the way they are intended to. So here are a few steps that one could perform to run unit-tests in a -local pagure instance. +local pagure instance. * Install the dependencies:: @@ -318,3 +338,14 @@ For example: :: yum install python-coverage + +To run the unit-tests, there is also a container available with all the dependencies needed. +Use the following command to run the tests :: + + $ ./dev/run-tests-docker.py + +This command will build a fedora based container and execute the test suite. You can also +limit the tests to unit-test files or single tests similar to the ``./runtests.sh`` +options described above. + +