#810 Improve pagure's documentation
Merged 3 years ago by pingou. Opened 3 years ago by pingou.

empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
empty or binary file added
file added
+80

@@ -0,0 +1,80 @@ 

+ First Steps on pagure

+ =====================

+ 

+ When coming to pagure for the first time there are a few things one should

+ do or check to ensure all works as desired.

+ 

+ Login to pagure or create your account

+ --------------------------------------

+ 

+ Pagure has its own user account system.

+ 

+ For instances of pagure such as the one at `pagure.io <https://pagure.io>`_

+ where the authentication is delegated to a third party (in the case of

+ pagure.io, the Fedora Account System) via OpenID, the local user account

+ is created upon login.

+ 

+ This means, you cannot be added to a group or a project before you login for

+ the first time as the system will simply not know you.

+ 

+ If you run your own pagure instance which uses the local authentication

+ system, then you will find on the login page an option to create a new

+ account.

+ 

+ 

+ Upload your SSH key

+ -------------------

+ 

+ Pagure uses gitolite to manage who has read/write access to which git

+ repository via `ssh <https://en.wikipedia.org/wiki/Secure_Shell>`_.

+ 

+ An ssh key is composed of two parts:

+ 

+ * a private key, which you must keep to yourself and never share with anyone.

+ * a public key, which is public and therefore can be shared with anyone.

+ 

+ If you have never generated a ssh key, you can do so by running:

+ 

+ ::

+ 

+     ssh-keygen

+ 

+ or alternatively on GNOME using the application ``seahorse``.

+ 

+ This will create two files in ``~/.ssh/`` (``~`` is the symbol for your home

+ folder).

+ 

+ These two files will be named (for example) ``id_rsa`` and ``id_rsa.pub``.

+ The first one is the private key that must never be shared. The second is

+ the public key that can be uploaded on pagure to give you ssh access.

+ 

+ To upload your public key onto pagure, login and click on the user icon on

+ the top right corner, there, select ``My settings``.

+ 

+ .. image:: _static/pagure_my_settings.png

+         :target: _static/pagure_my_settings.png

+ 

+ 

+ Configure the default email address

+ -----------------------------------

+ 

+ If the pagure instance you use is using local user authentication, then when

+ you created your account you could choose whichever email address you prefer

+ to use, but in the case (like pagure.io) where the pagure instance relies

+ on an external authentication service, the email address provided by this

+ service may be different from the one you prefer.

+ 

+ Your settings' page (cf the image above for how to access to the page) allow

+ you to add multiple email address and set one as default.

+ 

+ Your default email address is the address that will be used to send you

+ notifications and also as the email address in the git commit if you merge

+ a pull-request with a merge commit.

+ 

+ For online editing, when doing the commit, you will be presented with the

+ list of valid email addresses associated with your account and you will be

+ able to choose which one you wish to use.

+ 

+ .. note:: All email address will need to be confirmed to be activated, this

+           is done via a link sent by email to the address. If you do not

+           receive this link, don't forget to check your spam folder!

file added
+53

@@ -0,0 +1,53 @@ 

+                                             Grants/Denies access

+                                                +------------+                           +-----------+

+                                                |            |                           |           |

+      User's git actions+---------------------->|  Gitolite  +-------------------------->+ Git repos |

+                                                |            |                           |           |

+                                                +-----+------+                           +-----------+

+                                                      ^

+                                                      |

+                                                      |

+                                                      +------------------------------------------+

+                                                                                                 |

+                                                                                                 |

+                                                 +-------------------------+                     |

+                          Notifications          |                         |                     |

+            +------------------------------------+  Postfix                |<--------------------------------+

+            |                                    |                         |                     |           |

+            |                                    |     +-------------------+                     |           |

+            |                                    |     |                   |                     |           |

+            v                                    |     |  Pagure's milter  |                     |           |

+     User's mail client                          |     |                   +--------------+      |           |

+            +                                    +-----+--------+----------+              |      |           |

+            |                                                   ^                 Updates |      |           |

+            |                                                   |                         |      |           |

+            |             Replies                               |                         |      |           |

+            +---------------------------------------------------+                         |      |           |

+                                                                                          |      |           |

+                                                                                          |      |           |

+                                                 +--------------+                         |      |           |

+                                                 |              |                         |      |           |

+                        +----------------------->|  Pagure      |                         v      |           |

+                        |                        |  Doc server  |                   +------------+-+         |

+                        |                        |              |                   |{s}           |         |

+                        |                        +--------------+          +------->|   Database   |         |

+                        |                                                  |        |              |         |

+    User's web browser--+ http requests                            Updates |        +--------------+         |

+         ^              |                                         & queries|                                 |

+         |              |                                                  |                                 |

+         |              |                        +--------------+          |                                 |

+         |              |                        |              +----------+---------------------------------+

+         |              +----------------------->|  Pagure      |

+         |                                       |  web server  +---+           +----------------------+               +----------------+

+         |                                       |              |   |           |                      |               |                |

+         |                                       +--------------+   |           |  Pagure              |               |   Third Party  |

+         |                                                          +---------->|  Web hooks' server   +-------------->|   Services     |

+         |                                                          |           |                      |               |                |

+         |                                                    redis |           +----------------------+               +----------------+

+         |                                                          |

+         |                                                          |           +----------------------+

+         |                                                          +---------->|                      |

+         |                                                                      |  Pagure              |

+         +----------------------------------------------------------------------+  EventSource server  |

+                                Server-Sent Event                               |                      |

+                                                                                +----------------------+

file modified
+46

@@ -9,6 +9,20 @@ 

  .. contents::

  

  

+ Before going into the overall picture, one should realize that most of the

+ components listed above are optional.

+ 

+ Here is a diagram representing pagure without all the optionals components:

+ 

+ .. image:: _static/overview_simple.png

+         :target: _static/overview_simple.png

+ 

+ 

+ And here is a diagram of all the components together:

+ 

+ .. image:: _static/overview.png

+         :target: _static/overview.png

+ 

  Pagure core application

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

  

@@ -17,6 +31,18 @@ 

  This is the main application for the forge.

  

  

+ Gitolite

+ --------

+ 

+ Currently pagure uses `gitolite <http://gitolite.com/gitolite/index.html>`_

+ to grant or deny `ssh <https://en.wikipedia.org/wiki/Secure_Shell>`_ access

+ to the git repositories, in other words to grant or deny read and/or write

+ access to the git repositories.

+ 

+ Pagure supports cloning over both ssh and http, but writing can only be done

+ via ssh, through gitolite.

+ 

+ 

  Pagure doc server

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

  

@@ -56,3 +82,23 @@ 

  someone is viewing it. For example, while you are reading a ticket if someone

  comments on it, the comment will automatically show up on the page without

  the need for you to reload the entire page.

+ 

+ The flow is: the main pagure server does an action, sends a message over

+ redis, the eventsource server picks it up and send it to the browsers waiting

+ for it, then javascript code is executed to refresh the page based on the

+ information received.

+ 

+ 

+ Pagure web-hook Server

+ -------------------------

+ 

+ Sends notifications to third party services using POST http requests.

+ 

+ This is the second notifications system in pagure with `fedmsg <http://fedmsg.com/>`_.

+ These notifications are running on their own service to prevent blocking the

+ main web application in case the third part service is timing-out or just

+ being slow.

+ 

+ The flow is: the main pagure server does an action, sends a message over

+ redis, the web-hook server picks it up, build the query and performs the

+ POST request to the specified URLs.

@@ -0,0 +1,26 @@ 

+ 

+                                       Grants/Denies access

+                                          +------------+                           +-----------+

+                                          |cfffca4     |                           |           |

+ User's git actions+--------------------->+  Gitolite  +-------------------------->+ Git repos |

+                                          |            |                           |           |

+                                          +------------+                           +-----------+

+                                                  ^

+                                                  |

+                                                  +-----------------------------+

+                                                                                |

+ User's mail client                                                             |

+        ^                                  +---------------+                    |

+        |             Notifications        |               |                    |

+        +----------------------------------+  Mail server  |                    |

+                                           |               |                    |

+                                           +---------------+                    |

+                                                  ^                             |

+                                                  |                             |

+                                                  |                             |

+                                           +--------------+   Updates    +--------------+

+                                           |              |  & queries   |{s}           |

+ User's web browser+---------------------->+  Pagure      +------------->|   Database   |

+                                           |  web server  |              |              |

+                                           |              |              +--------------+

+                                           +--------------+

@@ -0,0 +1,74 @@ 

+ Customize the PR page

+ =====================

+ 

+ Pagure offers the possibility to customize the page that creates pull-request

+ to add your specific information, such as: please follow the XYZ coding style,

+ run the tests or whatever you wish to inform contributors when they open a

+ new pull-request.

+ 

+ The customization is done via a file in the git repository containing the

+ meta-data for the pull-requests. This file must be placed under a ``templates``

+ folder, be named ``contributing.md`` and can be formated as you wish using

+ markdown.

+ 

+ 

+ Example

+ -------

+ 

+ For a project named ``test`` on ``pagure.io``.

+ 

+ * First, clone the pull-request git repo [#f1]_ and move into it

+ 

+ ::

+ 

+     git clone ssh://git@pagure.org/requests/test.git

+     cd test

+ 

+ * Create the templates folder

+ 

+ ::

+ 

+     mkdir templates

+ 

+ * Create the customized PR info

+ 

+ ::

+ 

+     vim templates/contributing.md

+ 

+ And place in this file the following content:

+ 

+ ::

+ 

+     Contributing to test

+     ====================

+ 

+     When creating a pull-request against test, there are couple of items to do

+     that will speed up the review process:

+ 

+     * Ensure the unit-tests are all passing (cf the ``runtests.sh`` script at the

+       top level of the sources)

+     * Check if your changes are [pep8](https://www.python.org/dev/peps/pep-0008/)

+       compliant for this you can install ``python-pep8`` and run the ``pep8`` CLI

+       tool

+ 

+ 

+ * Commit and push the changes to the git repo

+ 

+ ::

+ 

+     git add templates

+     git commit -m "Customize the PR page"

+     git push

+ 

+ 

+ * And this is how it will look like

+ 

+ .. image:: _static/pagure_custom_pr.png

+         :target: _static/pagure_custom_pr.png

+ 

+ 

+ 

+ .. [#f1] All the URLs to the different git repositories can be found on the

+          main page of the project, on the right-side menu, under the section

+          ``Source GIT URLs``, click on ``more`` to see them.

@@ -0,0 +1,77 @@ 

+ Templates for ticket input

+ ==========================

+ 

+ Pagure offers the possibility to add templates for ticket's input. These

+ templates do not enforce anything, users will have the possibility to simply

+ ignore it, or even to not follow it, but it also helps structuring the

+ ticket opened against a project and highlighting the information that are

+ often requested/needed.

+ 

+ The templates are provided in the git repository containing the meta-data

+ for the tickets.

+ They must be placed under a ``templates`` folder in this git repository,

+ end with ``.md``and as the extension suggests can be formated as markdown.

+ 

+ If you create a template ``templates/default.md``, it will be shown by

+ default when someone ask to create a new ticket.

+ 

+ 

+ 

+ Example

+ -------

+ 

+ For a project named ``test`` on ``pagure.io``.

+ 

+ * First, clone the ticket git repo [#f1]_ and move into it

+ 

+ ::

+ 

+     git clone ssh://git@pagure.io/tickets/pagure.git

+     cd test

+ 

+ * Create the templates folder

+ 

+ ::

+ 

+     mkdir templates

+ 

+ * Create a default template

+ 

+ ::

+ 

+     vim templates/default.md

+ 

+ And place in this file the following content:

+ 

+ ::

+ 

+     ##### Issue

+ 

+     ##### Steps to reproduce

+     1.

+     2.

+     3.

+ 

+     ##### Actual results

+ 

+     ##### Expected results

+ 

+ * Commit and push the changes to the git repo

+ 

+ ::

+ 

+     git add templates

+     git commit -m "Add a default template for tickets"

+     git push

+ 

+ 

+ * And this is how it will look like

+ 

+ .. image:: _static/pagure_ticket_template.png

+         :target: _static/pagure_ticket_template.png

+ 

+ 

+ 

+ .. [#f1] All the URLs to the different git repositories can be found on the

+          main page of the project, on the right-side menu, under the section

+          ``Source GIT URLs``, click on ``more`` to see them.

file modified
+3

@@ -10,4 +10,7 @@ 

  .. toctree::

     :maxdepth: 2

  

+    first_steps

+    ticket_templates

+    pr_custom_page

     theming

no initial comment

Pull-Request has been rebased

3 years ago

Pull-Request has been rebased

3 years ago

s/for example/alternatively/

How do the services communicate with the main process? unix pipes? redis queues? smoke signals? carrier pigeons?

maybe s/to create/that creates/

s/are providing/are provided/ ?

Looks good overall. I left a couple comments, but :+1: nonetheless.

Pull-Request has been updated

3 years ago

I think I could address all the points you mentioned.

Let's merge and adjust again in the future if/when needed :)

Pull-Request has been merged by pingou

3 years ago