PR#810: Improve pagure's documentation - pagure

		`@@ -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!`

doc/overview.ascii

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 \| \|`
		`+ +----------------------+`

doc/overview.rst

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.`

doc/overview_simple.ascii

file added

+26

		`@@ -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 \| \| \|`
		`+ \| \| +--------------+`
		`+ +--------------+`

doc/pr_custom_page.rst

file added

+74

		`@@ -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.

doc/ticket_templates.rst

file added

+77

		`@@ -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.

doc/usage.rst

file modified

		`@@ -10,4 +10,7 @@`
		`.. toctree::`
		`:maxdepth: 2`

		`+ first_steps`
		`+ ticket_templates`
		`+ pr_custom_page`
		`theming`

no initial comment

Pull-Request has been rebased

8 years ago

Pull-Request has been rebased

8 years ago

ralph commented on line 13 of doc/first_steps.rst 8 years ago

s/in/at/

ralph commented on line 43 of doc/first_steps.rst 8 years ago

s/for example/alternatively/

ralph commented on line 55 of doc/overview.rst 8 years ago

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

ralph commented on line 5 of doc/pr_custom_page.rst 8 years ago

maybe s/to create/that creates/

ralph commented on line 11 of doc/ticket_templates.rst 8 years ago

s/are providing/are provided/ ?

ralph commented 8 years ago

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

Pull-Request has been updated

8 years ago

pingou commented 8 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

8 years ago

Metadata

Assignee

None

Tags

No Tags

Changes Summary 12

file added

doc/_static/overview.png

file added

doc/_static/overview_simple.png

file added

doc/_static/pagure_custom_pr.png

file added

doc/_static/pagure_my_settings.png

file added

doc/_static/pagure_ticket_template.png

file added

file added

file added

doc/overview_simple.ascii

+74

file added

doc/pr_custom_page.rst

+77

file added

doc/ticket_templates.rst

+3 -0

file changed

doc/usage.rst

		`@@ -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 \| \|`
		`+ +----------------------+`

		`@@ -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 \| \| \|`
		`+ \| \| +--------------+`
		`+ +--------------+`

pagure

Source Code

Documentation

#810 Improve pagure's documentation Merged 8 years ago by pingou. Opened 8 years ago by pingou. more_doc into master

Metadata

Changes Summary 12

#810 Improve pagure's documentation

Merged 8 years ago by pingou. Opened 8 years ago by pingou.

more_doc into master