From 63c35e7a6ae090f09079a7ccee25a5493d88fd00 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:27 +0000 Subject: [PATCH 1/12] Add a diagram presenting an overview of all the components --- diff --git a/doc/overview.ascii b/doc/overview.ascii new file mode 100644 index 0000000..10d6167 --- /dev/null +++ b/doc/overview.ascii @@ -0,0 +1,41 @@ + +-------------------------+ + Notifications | | + +------------------------------------+ Postfix |<--------------------------------+ + | | | | + | | +-------------------+ | + | | | | | + v | | Pagure's milter | | + User's mail client | | +--------------+ | + + +-----+--------+----------+ | | + | ^ | | + | | | | + | Replies | |Updates | + +---------------------------------------------------+ | | + | | + | | + +--------------+ | | + | | | | + +----------------------->| Pagure | v | + | | Doc server | +--------------+ | + | | | | | | + | +--------------+ +------->| 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 | | + +----------------------+ From cd8e875aaacfb1e31ed1fcba7c57d71052d5bf9a Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 2/12] Mention the web-hook server in the overview page --- diff --git a/doc/overview.rst b/doc/overview.rst index 1ca818e..eab1077 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -56,3 +56,14 @@ For pagure this technology is used to allow live-refreshing of a page when 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. + + +Pagure web-hook Server +------------------------- + +Sends notifications to third party services using POST http requests. + +This is the second notifications system in pagure with `fedmsg `_. +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. From c3158fa93a2d77294191af15ba82233e12eeb53b Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 3/12] Include gitolite in the overview diagram --- diff --git a/doc/overview.ascii b/doc/overview.ascii index 10d6167..648bfa3 100644 --- a/doc/overview.ascii +++ b/doc/overview.ascii @@ -1,26 +1,38 @@ - +-------------------------+ - Notifications | | + Grants/Denies access + +------------+ +-----------+ + | | | | + User's git actions+---------------------->| Gitolite +-------------------------->+ Git repos | + | | | | + +-----+------+ +-----------+ + ^ + | + | + +------------------------------------------+ + | + | + +-------------------------+ | + Notifications | | | +------------------------------------+ Postfix |<--------------------------------+ - | | | | - | | +-------------------+ | - | | | | | - v | | Pagure's milter | | - User's mail client | | +--------------+ | - + +-----+--------+----------+ | | - | ^ | | - | | | | - | Replies | |Updates | - +---------------------------------------------------+ | | - | | - | | - +--------------+ | | - | | | | - +----------------------->| Pagure | v | - | | Doc server | +--------------+ | + | | | | | + | | +-------------------+ | | + | | | | | | + v | | Pagure's milter | | | + User's mail client | | +--------------+ | | + + +-----+--------+----------+ | | | + | ^ Updates | | | + | | | | | + | Replies | | | | + +---------------------------------------------------+ | | | + | | | + | | | + +--------------+ | | | + | | | | | + +----------------------->| Pagure | v | | + | | Doc server | +------------+-+ | | | | | | | | +--------------+ +------->| Database | | | | | | | - User's web browser--+ http requests Updates | +--------------+ | + User's web browser--+ Updates | +--------------+ | ^ | & queries| | | | | | | | +--------------+ | | @@ -37,5 +49,5 @@ | +---------->| | | | Pagure | +----------------------------------------------------------------------+ EventSource server | - Server Sent Event | | + Server-Sent Event | | +----------------------+ From 2b448e2a10b4148e8d47d488faab1805e9254172 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 4/12] Place the overview diagram in the overview page --- diff --git a/doc/_static/overview.png b/doc/_static/overview.png new file mode 100644 index 0000000..2fcd7a9 Binary files /dev/null and b/doc/_static/overview.png differ diff --git a/doc/overview.rst b/doc/overview.rst index eab1077..27cf656 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -9,6 +9,12 @@ These components are: .. contents:: +And since a picture is worth thousand words, here is a diagram of all these +components together: + +.. image:: _static/overview.png + :target: _static/overview.png + Pagure core application ----------------------- From 8d07f25bb504e2465c7e8ba1bdeda035a20ae8cb Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 5/12] Add documentation on how to create templates for tickets --- diff --git a/doc/_static/pagure_ticket_template.png b/doc/_static/pagure_ticket_template.png new file mode 100644 index 0000000..3153907 Binary files /dev/null and b/doc/_static/pagure_ticket_template.png differ diff --git a/doc/ticket_templates.rst b/doc/ticket_templates.rst new file mode 100644 index 0000000..aac6518 --- /dev/null +++ b/doc/ticket_templates.rst @@ -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 providing 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. diff --git a/doc/usage.rst b/doc/usage.rst index 6253d99..ec62a02 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -11,3 +11,4 @@ Contents: :maxdepth: 2 theming + ticket_templates From a49ea7777f64b3802fbf9cce5637cc7bbbf83b28 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 6/12] Add documentation on how to customize the PR page --- diff --git a/doc/_static/pagure_custom_pr.png b/doc/_static/pagure_custom_pr.png new file mode 100644 index 0000000..5086d23 Binary files /dev/null and b/doc/_static/pagure_custom_pr.png differ diff --git a/doc/pr_custom_page.rst b/doc/pr_custom_page.rst new file mode 100644 index 0000000..d1e57ee --- /dev/null +++ b/doc/pr_custom_page.rst @@ -0,0 +1,74 @@ +Customize the PR page +===================== + +Pagure offers the possibility to customize the page to create 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. diff --git a/doc/usage.rst b/doc/usage.rst index ec62a02..c7985ba 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -12,3 +12,4 @@ Contents: theming ticket_templates + pr_custom_page From 8cb43f457239d70d9d755f45b06e92fd81458eae Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 7/12] Small update of the overview diagram --- diff --git a/doc/_static/overview.png b/doc/_static/overview.png index 2fcd7a9..fe3f4e8 100644 Binary files a/doc/_static/overview.png and b/doc/_static/overview.png differ diff --git a/doc/overview.ascii b/doc/overview.ascii index 648bfa3..2181bfa 100644 --- a/doc/overview.ascii +++ b/doc/overview.ascii @@ -32,7 +32,7 @@ | | | | | | | +--------------+ +------->| Database | | | | | | | - User's web browser--+ Updates | +--------------+ | + User's web browser--+ http requests Updates | +--------------+ | ^ | & queries| | | | | | | | +--------------+ | | From 6670db144dddd78dcf9519451f9eaafc2927fa71 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 8/12] Make the database look like a database in the diagram --- diff --git a/doc/_static/overview.png b/doc/_static/overview.png index fe3f4e8..32c8531 100644 Binary files a/doc/_static/overview.png and b/doc/_static/overview.png differ diff --git a/doc/overview.ascii b/doc/overview.ascii index 2181bfa..3c003cd 100644 --- a/doc/overview.ascii +++ b/doc/overview.ascii @@ -29,7 +29,7 @@ | | | | | +----------------------->| Pagure | v | | | | Doc server | +------------+-+ | - | | | | | | + | | | |{s} | | | +--------------+ +------->| Database | | | | | | | User's web browser--+ http requests Updates | +--------------+ | From 8bbf2614a65b553677e7139c890044f6007d0cd2 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 9/12] Add a section about gitolite in the overview page --- diff --git a/doc/overview.rst b/doc/overview.rst index 27cf656..7313cf9 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -23,6 +23,18 @@ provide a web UI to the git repositories as well as tickets and pull-requests. This is the main application for the forge. +Gitolite +-------- + +Currently pagure uses `gitolite `_ +to grant or deny `ssh `_ 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 ----------------- From dd9db6c70077aa3954c0aa488de56ad8533bef33 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 10/12] Add a simplified overview diagram with only the core components --- diff --git a/doc/_static/overview_simple.png b/doc/_static/overview_simple.png new file mode 100644 index 0000000..f898461 Binary files /dev/null and b/doc/_static/overview_simple.png differ diff --git a/doc/overview.rst b/doc/overview.rst index 7313cf9..bc14f8b 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -9,8 +9,16 @@ These components are: .. contents:: -And since a picture is worth thousand words, here is a diagram of all these -components together: +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 diff --git a/doc/overview_simple.ascii b/doc/overview_simple.ascii new file mode 100644 index 0000000..a1a129b --- /dev/null +++ b/doc/overview_simple.ascii @@ -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 | | | + | | +--------------+ + +--------------+ From 508cefb49482073842318ff26449c1a80a20e844 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 11 2016 16:50:28 +0000 Subject: [PATCH 11/12] Add a small doc on the recommended first steps for users on pagure --- diff --git a/doc/_static/pagure_my_settings.png b/doc/_static/pagure_my_settings.png new file mode 100644 index 0000000..d7fb5c7 Binary files /dev/null and b/doc/_static/pagure_my_settings.png differ diff --git a/doc/first_steps.rst b/doc/first_steps.rst new file mode 100644 index 0000000..d1fe76e --- /dev/null +++ b/doc/first_steps.rst @@ -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 in `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 `_. + +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 for example 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! diff --git a/doc/usage.rst b/doc/usage.rst index c7985ba..0f7e850 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -10,6 +10,7 @@ Contents: .. toctree:: :maxdepth: 2 - theming + first_steps ticket_templates pr_custom_page + theming From d89186a76bd682b4d885e66e85f2e2a944a57958 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Mar 12 2016 08:15:47 +0000 Subject: [PATCH 12/12] Adjust documentation based on the feedback from Ralph --- diff --git a/doc/first_steps.rst b/doc/first_steps.rst index d1fe76e..cdb42e4 100644 --- a/doc/first_steps.rst +++ b/doc/first_steps.rst @@ -9,7 +9,7 @@ Login to pagure or create your account Pagure has its own user account system. -For instances of pagure such as the one in `pagure.io `_ +For instances of pagure such as the one at `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. @@ -39,7 +39,7 @@ If you have never generated a ssh key, you can do so by running: ssh-keygen -or for example on GNOME using the application ``seahorse``. +or alternatively on GNOME using the application ``seahorse``. This will create two files in ``~/.ssh/`` (``~`` is the symbol for your home folder). diff --git a/doc/overview.rst b/doc/overview.rst index bc14f8b..cc4e06b 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -83,6 +83,11 @@ 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 ------------------------- @@ -93,3 +98,7 @@ This is the second notifications system in pagure with `fedmsg