From 0681341083c824af423afed77f743629852072f9 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 1/22] Include the descriptions of the different git repo in the usage page --- diff --git a/doc/usage.rst b/doc/usage.rst index 310384a..c618f1a 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -5,6 +5,34 @@ Using pagure should come fairly easily, especially to people already used to forges such as GitHub or GitLab. There are however some tips and tricks which can be useful to know and that this section of the doc covers. + +One of the major difference with GitHub and GitLab is that for each project +on pagure, four git repositories are made available to the admins of the +project: + +* A git repository containing the source code, displayed in the main section + of the pagure project. +* A git repository for the documentation +* A git repository for the issues and their metadata +* A git repository for the metadata for pull-requests + + +You can find the URLs to access or clone these git repositories on the +overview page of the project. On the menu on the right side, there is a menu +`Source GIT URLs`, next to it is a little `more` button, by clicking on it +you will be given the URLs to the other three git repos. + +Each section correspond to one of the four git repositories created for each +project: + +* A git repository containing the source code, displayed in the main section + of the pagure project. +* A git repository for the documentation +* A git repository for the issues and their metadata +* A git repository for the metadata for pull-requests + + + Contents: .. toctree:: diff --git a/doc/using_doc.rst b/doc/using_doc.rst index b4e1bfa..d56535d 100644 --- a/doc/using_doc.rst +++ b/doc/using_doc.rst @@ -1,20 +1,6 @@ Using the doc repository of your project ======================================== -On the overview page of your project, on the menu on the right side, are -presented the `Source GIT URLs`. Next to this title is a little `more` button. -If you click on this, you can see three more sections appearing: `Docs -GIT URLs`, `Issues GIT URLs` and `Pull Requests GIT URLs`. - -Each section correspond to one of the four git repositories created for each -project: - -* A git repository containing the source code, displayed in the main section - of the pagure project. -* A git repository for the documentation -* A git repository for the issues and their metadata -* A git repository for the metadata for pull-requests - In this section of the documentation, we are interested in the doc repository. The doc repository is a simple git repo, whose content will appear under the From b5fb9ab83a51d24bd18319a73957b2203128357d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 2/22] Start the documentation about web-hooks --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst new file mode 100644 index 0000000..507fd1b --- /dev/null +++ b/doc/using_webhooks.rst @@ -0,0 +1,6 @@ +Using web-hooks +=============== + +Web-hooks are a notification system that could be compared to a callback. +Basically, pagure will make a HTTP POST request to one or more third party +server/application with information about what is or just happened. From f694ba3e199824c9f281dcff5dda650bbeda2633 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 3/22] Continue working on the web-hook documentation --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst index 507fd1b..a31dd48 100644 --- a/doc/using_webhooks.rst +++ b/doc/using_webhooks.rst @@ -4,3 +4,10 @@ Using web-hooks Web-hooks are a notification system that could be compared to a callback. Basically, pagure will make a HTTP POST request to one or more third party server/application with information about what is or just happened. + +To set-up a web-hook, simply go to the settings page of your project and +enter the URL to the server that will receive the notifications. + +In the settings page is also present a web-hook key which is used by the +server to sign the message sent and which you can use to ensure the +notifications received are coming from the right source. From 414e87d40b5eb3c3a81e1a553df77a1e3317bda0 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 4/22] Start documentating the specific headers sent with the POST request --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst index a31dd48..72275fd 100644 --- a/doc/using_webhooks.rst +++ b/doc/using_webhooks.rst @@ -11,3 +11,18 @@ enter the URL to the server that will receive the notifications. In the settings page is also present a web-hook key which is used by the server to sign the message sent and which you can use to ensure the notifications received are coming from the right source. + +Each POST request made contains two specific headers: + +:: + + X-Pagure-Topic + X-Pagure-Signature + + +``X-Pagure-Topic`` is a global header giving a clue about the type of action +that just occured. For example ``issue.edit``. + + +``X-Pagure-Signature`` contains the signature of the message allowing to +check that the message comes from pagure. From 72c25a6c75e12002c5a95b4b073d15ad5e2c1d5d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 5/22] Document how to validate the signature attached to web-hook notifications --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst index 72275fd..72c4d72 100644 --- a/doc/using_webhooks.rst +++ b/doc/using_webhooks.rst @@ -26,3 +26,21 @@ that just occured. For example ``issue.edit``. ``X-Pagure-Signature`` contains the signature of the message allowing to check that the message comes from pagure. + + +Pagure relies on ``hmac`` to sign the content of its messages. If you want +to validate the message, in python you can simply do something like this: + +:: + + import hmac + + payload = # content you received in the POST request + headers = # headers of the POST request + project_web_hook_key = # private web-hook key of the project + + hashhex = hmac.new( + str(project_web_hook_key), payload, hashlib.sha1).hexdigest() + + if hashhex != headers.get('X-Pagure-Signature'): + raise Exception('Message received with an invalid signature') From 010886ab4b28a05cd02687ad65c7f52c3bbddb99 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 6/22] Add missing import for running the example code --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst index 72c4d72..2033e4f 100644 --- a/doc/using_webhooks.rst +++ b/doc/using_webhooks.rst @@ -34,6 +34,7 @@ to validate the message, in python you can simply do something like this: :: import hmac + import hashlib payload = # content you received in the POST request headers = # headers of the POST request From ed2aeb9e7e05f2841c14b526b82f6e0c9df46eca Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:18 +0000 Subject: [PATCH 7/22] Reformulate a little the doc on web-hooks --- diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst index 2033e4f..0040b1e 100644 --- a/doc/using_webhooks.rst +++ b/doc/using_webhooks.rst @@ -29,7 +29,7 @@ check that the message comes from pagure. Pagure relies on ``hmac`` to sign the content of its messages. If you want -to validate the message, in python you can simply do something like this: +to validate the message, in python, you can do something like the following: :: From e51ba94878088886d66d23cfe0c30b30f39831f3 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 8/22] Include the web-hooks documentation in the usage section --- diff --git a/doc/usage.rst b/doc/usage.rst index c618f1a..3f93646 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -40,6 +40,7 @@ Contents: first_steps using_doc + using_webhooks ticket_templates pr_custom_page theming From 6941688622a73fdb3b681abdd2ae88686041143d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 9/22] Add documentation about the `Activate always merge` setting --- diff --git a/doc/project_settings.rst b/doc/project_settings.rst index b50081e..4f8600e 100644 --- a/doc/project_settings.rst +++ b/doc/project_settings.rst @@ -8,6 +8,26 @@ to the project. This page presents the different settings and there effect. +`Activate always merge` +------------------------ + +This boolean enables or disables always making a merge commit when merging +a pull-request. + +When merging a pull-request in pagure there are three states: + +* fast-forward: when the commits in the pull-request can be fast-forwarded +pagure signals it and just fast-forward the commit, keeping the history linear. +* merge: when the commits in the pull-request cannot be merged without a merge +commit, pagure signals it and performs this merge commit. +* conflicts: when the commits in the pull-request cannot be merged at all +automatically due to one or more conflicts. Then pagure signals it and prevent +merging. + +If the `Activate always merge` option is on, then the `fast-forward` option +above is disabled in favor of the `merge` option. + + Issue tracker ------------- From 91c8e547187f7f17fc1191685f40f598a18e116a Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 10/22] Add documentation about the `Activate comment editing` setting --- diff --git a/doc/project_settings.rst b/doc/project_settings.rst index 4f8600e..419c0e2 100644 --- a/doc/project_settings.rst +++ b/doc/project_settings.rst @@ -28,6 +28,22 @@ If the `Activate always merge` option is on, then the `fast-forward` option above is disabled in favor of the `merge` option. +`Activate comment editing` +-------------------------- + +This boolean enables or disables editing comments. + +After commenting on a ticket or a pull-request, the admins of the project +and the author of the comment may be allowed to edit the comment. +This allows them to adjust the wording or the style as they wish. + +.. note:: notification about a comment is only sent once with the original + text, changes performed later will not trigger a new notification. + +Some project may not want to allow editing comments after they were posted +and this setting allows turning it on or off. + + Issue tracker ------------- From d665ecdda5fef6e41266f422a7e2dde323b66909 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 11/22] Document the `Activate Enforce signed-off commits in pull-request` setting --- diff --git a/doc/project_settings.rst b/doc/project_settings.rst index 419c0e2..4f89a57 100644 --- a/doc/project_settings.rst +++ b/doc/project_settings.rst @@ -44,6 +44,19 @@ Some project may not want to allow editing comments after they were posted and this setting allows turning it on or off. +`Activate Enforce signed-off commits in pull-request` +----------------------------------------------------- + +This boolean enables or disables checking for a 'Signed-off-by' line (case +insensitive) in the commit messages of the pull-requests. + +If this line is missing, pagure will display a message near the `Merge` +button, allowing project admin to request the PR to be updated. + +.. note:: This setting does not prevent commits without this 'signed-off-by' + line to be pushed directly, it only work at the pull-request level. + + Issue tracker ------------- From 36c7fc59790fb9b610aeb3edd487a4c28ccf0b40 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 12/22] Adjust the titles for the existing sections to fit the name in the settings page --- diff --git a/doc/project_settings.rst b/doc/project_settings.rst index 4f89a57..6dd923c 100644 --- a/doc/project_settings.rst +++ b/doc/project_settings.rst @@ -57,16 +57,16 @@ button, allowing project admin to request the PR to be updated. line to be pushed directly, it only work at the pull-request level. -Issue tracker -------------- +`Activate issue tracker` +------------------------ This boolean simply enables or disables the issue tracker for the project. So if you are tracking your ticket on a different system, you can simply disable reporting issue on pagure by un-checking this option. -Project documentation ---------------------- +`Activate project documentation` +-------------------------------- Pagure offers the option to have a git repository specific for the documentation of the project. @@ -79,8 +79,8 @@ the sources of the project, you can disable the ``Docs`` tab by un-checking this option. -Pull-request ------------- +`Activate pull requests` +------------------------ Pagure offers the option to fork a project, make changes to it and then ask the developer to merge these changes into the project. This is similar to @@ -94,8 +94,8 @@ prevent anyone from opening a pull-request against this project. .. note:: disabling pull-requests does *not* disable forking the projects. -Only assignee can merge pull-request ------------------------------------- +`Activate Only assignee can merge pull-request` +----------------------------------------------- This option can be used for project wishing to institute a strong review workflow where pull-request are first assigned then merged. @@ -104,8 +104,8 @@ If this option is enabled, only the person assigned to the pull-request can merge it. -Minimum score to merge pull-request ------------------------------------ +`Activate Minimum score to merge pull-request` +---------------------------------------------- This option can be used for project wishing to enforce having a minimum number of people reviewing a pull-request before it can be merged. @@ -131,8 +131,8 @@ To vote against a pull-request, use either: .. note:: Anyone can vote on the pull-request, not only the contributors. -Web-hooks ---------- +`Activate Web-hooks` +-------------------- Pagure offers the option of sending notification about event happening on a project via [web-hooks|https://en.wikipedia.org/wiki/Webhook]. This option From 82f2ff01a14aa0ff8b661e1e1ba7a802920f179d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 13/22] Re-order the documentation about project settings to fit the UI --- diff --git a/doc/project_settings.rst b/doc/project_settings.rst index 6dd923c..2350a0c 100644 --- a/doc/project_settings.rst +++ b/doc/project_settings.rst @@ -65,6 +65,43 @@ So if you are tracking your ticket on a different system, you can simply disable reporting issue on pagure by un-checking this option. +`Activate Minimum score to merge pull-request` +---------------------------------------------- + +This option can be used for project wishing to enforce having a minimum +number of people reviewing a pull-request before it can be merged. + +If this option is enabled, anyone can vote in favor or against a pull-request +and the sum of the votes in favor minus the sum of the votes againsts give +the pull-request a score that should be equal or great to the value +entered in this option for the pull-request to be allowed to be merged. + +.. note:: Only the main comments (ie: not in-line) are taken into account + to calculate the score of the pull-request. + +To vote in favor of a pull-request, use either: +* ``+1`` +* ``:thumbsup:`` + +To vote against a pull-request, use either: +* ``-1`` +* ``:thumbsdown:`` + +.. note:: Pull-Request reaching the minimum score are not automatically merged + +.. note:: Anyone can vote on the pull-request, not only the contributors. + + +`Activate Only assignee can merge pull-request` +----------------------------------------------- + +This option can be used for project wishing to institute a strong review +workflow where pull-request are first assigned then merged. + +If this option is enabled, only the person assigned to the pull-request +can merge it. + + `Activate project documentation` -------------------------------- @@ -94,43 +131,6 @@ prevent anyone from opening a pull-request against this project. .. note:: disabling pull-requests does *not* disable forking the projects. -`Activate Only assignee can merge pull-request` ------------------------------------------------ - -This option can be used for project wishing to institute a strong review -workflow where pull-request are first assigned then merged. - -If this option is enabled, only the person assigned to the pull-request -can merge it. - - -`Activate Minimum score to merge pull-request` ----------------------------------------------- - -This option can be used for project wishing to enforce having a minimum -number of people reviewing a pull-request before it can be merged. - -If this option is enabled, anyone can vote in favor or against a pull-request -and the sum of the votes in favor minus the sum of the votes againsts give -the pull-request a score that should be equal or great to the value -entered in this option for the pull-request to be allowed to be merged. - -.. note:: Only the main comments (ie: not in-line) are taken into account - to calculate the score of the pull-request. - -To vote in favor of a pull-request, use either: -* ``+1`` -* ``:thumbsup:`` - -To vote against a pull-request, use either: -* ``-1`` -* ``:thumbsdown:`` - -.. note:: Pull-Request reaching the minimum score are not automatically merged - -.. note:: Anyone can vote on the pull-request, not only the contributors. - - `Activate Web-hooks` -------------------- From 6772ba51f231ded8c8e7f435c18b2a4ef39cbcca Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 14/22] Include the project settings doc in the usage section of the doc --- diff --git a/doc/usage.rst b/doc/usage.rst index 3f93646..1a4bb7b 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -39,6 +39,7 @@ Contents: :maxdepth: 2 first_steps + project_settings using_doc using_webhooks ticket_templates From facfaf0828dd08ac7b1da4b5304ee18e4f3bf11b Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 15/22] Document how to stamp your db for alembic after creating it. --- diff --git a/doc/install.rst b/doc/install.rst index 996de56..c1269ce 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -229,3 +229,31 @@ For example: This will tell ``/usr/share/pagure/pagure_createdb.py`` to use the database information specified in the file ``/etc/pagure/pagure.cfg``. + +* Stamp the alembic revision + +For changes to existing tables, we rely on `Alembic `_. +It uses `revisions` to perform the upgrades, but to know which upgrades are +needed and which are already done, the current revision needs to be saved +in the database. This will allow alembic to know apply the new revision when +running it. + +You can save the current revision in the database using the following command: +:: + + cd /etc/pagure + alembic stamp $(alembic heads |awk '{ print $1 }') + +The ``cd /etc/pagure`` is needed as the command must be run in the folder +where is the file ``alembic.ini``. This file contains two important +information: + +* ``sqlalchemy.url`` which is the URL used to connect to the database, likely +the same URL as the one in ``pagure.cfg``. +* ``script_location`` which is the path to the ``versions`` folder containing +all the alembic migration files. + +The ``alembic stamp`` command is the one actually saving the current revision +into the database. This current revision is found using ``alembic heads`` +which returns the most recent revision found by alembic, and since the +database was just created, it is at the latest revision. From 651b3498738be4df3d60250d1554a4146ae38e16 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 16/22] Add some documentation about DB schema migration --- diff --git a/doc/upgrade_db.rst b/doc/upgrade_db.rst new file mode 100644 index 0000000..6c3ebe3 --- /dev/null +++ b/doc/upgrade_db.rst @@ -0,0 +1,48 @@ +Upgrade a database +================== + + +Database schema migration are handled in two ways: + +* New tables + +For this we simply rely on the ``createdb`` script used when creating the +database the first time. + +* Changes to existing tables + +For changes to existing tables, we rely on `Alembic `_. +This allows us to do upgrade and downgrade of schema migration, kind of like +one would do commits in a system like git. + +To upgrade the database to the latest version simply run: +:: + + alembic upgrade head + +This may fail for different reasons: + +* The change was already made in the database + +This can be because the version of the database schema saved is incorrect. +It can be debugged using the following commands: + + * Find the current revision: ``alembic current`` + * See the entire history: ``alembic history`` + +Once the revision at which your database should be is found (in the history) +you can declare that your database is at this given revision using: +``alembic stamp ``. + +Eventually, if you do not know where your database is or should be, you can +do an iterative process stamping the database for every revision, one by one +trying everytime to ``alembic upgrade`` until it works. + +* The database used does not support some of the changes + +SQLite is handy for development but does not support all the features of a +real database server. Upgrading a SQLite database might therefore not work, +depending on the changes done. + +In some cases, if you are using a SQLite database, you will have to destroy +it and create a new one. diff --git a/doc/usage.rst b/doc/usage.rst index 1a4bb7b..9ee08e4 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -45,3 +45,4 @@ Contents: ticket_templates pr_custom_page theming + upgrade_db From 4fca2207584aca6f759033dec697954470add4e7 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 18 2016 09:57:19 +0000 Subject: [PATCH 17/22] Move the usage docs into their own folder to keep things structured --- diff --git a/doc/first_steps.rst b/doc/first_steps.rst deleted file mode 100644 index cdb42e4..0000000 --- a/doc/first_steps.rst +++ /dev/null @@ -1,80 +0,0 @@ -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 `_ -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 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! diff --git a/doc/pr_custom_page.rst b/doc/pr_custom_page.rst deleted file mode 100644 index 86aa195..0000000 --- a/doc/pr_custom_page.rst +++ /dev/null @@ -1,74 +0,0 @@ -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. diff --git a/doc/project_settings.rst b/doc/project_settings.rst deleted file mode 100644 index 2350a0c..0000000 --- a/doc/project_settings.rst +++ /dev/null @@ -1,145 +0,0 @@ -Project settings -================ - -Each project have a number of options that can be tweaked in the settings -page of the project which is accessible to the person having full commits -to the project. - -This page presents the different settings and there effect. - - -`Activate always merge` ------------------------- - -This boolean enables or disables always making a merge commit when merging -a pull-request. - -When merging a pull-request in pagure there are three states: - -* fast-forward: when the commits in the pull-request can be fast-forwarded -pagure signals it and just fast-forward the commit, keeping the history linear. -* merge: when the commits in the pull-request cannot be merged without a merge -commit, pagure signals it and performs this merge commit. -* conflicts: when the commits in the pull-request cannot be merged at all -automatically due to one or more conflicts. Then pagure signals it and prevent -merging. - -If the `Activate always merge` option is on, then the `fast-forward` option -above is disabled in favor of the `merge` option. - - -`Activate comment editing` --------------------------- - -This boolean enables or disables editing comments. - -After commenting on a ticket or a pull-request, the admins of the project -and the author of the comment may be allowed to edit the comment. -This allows them to adjust the wording or the style as they wish. - -.. note:: notification about a comment is only sent once with the original - text, changes performed later will not trigger a new notification. - -Some project may not want to allow editing comments after they were posted -and this setting allows turning it on or off. - - -`Activate Enforce signed-off commits in pull-request` ------------------------------------------------------ - -This boolean enables or disables checking for a 'Signed-off-by' line (case -insensitive) in the commit messages of the pull-requests. - -If this line is missing, pagure will display a message near the `Merge` -button, allowing project admin to request the PR to be updated. - -.. note:: This setting does not prevent commits without this 'signed-off-by' - line to be pushed directly, it only work at the pull-request level. - - -`Activate issue tracker` ------------------------- - -This boolean simply enables or disables the issue tracker for the project. -So if you are tracking your ticket on a different system, you can simply -disable reporting issue on pagure by un-checking this option. - - -`Activate Minimum score to merge pull-request` ----------------------------------------------- - -This option can be used for project wishing to enforce having a minimum -number of people reviewing a pull-request before it can be merged. - -If this option is enabled, anyone can vote in favor or against a pull-request -and the sum of the votes in favor minus the sum of the votes againsts give -the pull-request a score that should be equal or great to the value -entered in this option for the pull-request to be allowed to be merged. - -.. note:: Only the main comments (ie: not in-line) are taken into account - to calculate the score of the pull-request. - -To vote in favor of a pull-request, use either: -* ``+1`` -* ``:thumbsup:`` - -To vote against a pull-request, use either: -* ``-1`` -* ``:thumbsdown:`` - -.. note:: Pull-Request reaching the minimum score are not automatically merged - -.. note:: Anyone can vote on the pull-request, not only the contributors. - - -`Activate Only assignee can merge pull-request` ------------------------------------------------ - -This option can be used for project wishing to institute a strong review -workflow where pull-request are first assigned then merged. - -If this option is enabled, only the person assigned to the pull-request -can merge it. - - -`Activate project documentation` --------------------------------- - -Pagure offers the option to have a git repository specific for the -documentation of the project. - -This repository is then accessible under the ``Docs`` tab in the menu of the -project. - -If you prefer to store your documentation elsewhere or maybe even within -the sources of the project, you can disable the ``Docs`` tab by un-checking -this option. - - -`Activate pull requests` ------------------------- - -Pagure offers the option to fork a project, make changes to it and then ask -the developer to merge these changes into the project. This is similar to -the pull-request mechanism on GitHub or GitLab. - -However, some projects may prefer receiving patches by email on their list -or via another hosting plateform or simply do not wish to use the -pull-request mechanism at all. Un-checking this option will therefore -prevent anyone from opening a pull-request against this project. - -.. note:: disabling pull-requests does *not* disable forking the projects. - - -`Activate Web-hooks` --------------------- - -Pagure offers the option of sending notification about event happening on a -project via [web-hooks|https://en.wikipedia.org/wiki/Webhook]. This option -is off by default and can be turned on for a pagure instance in its -configuration file. - -The URL of the web-hooks can be entered in this field. - -.. note:: See the ``notifications`` documentation to learn more about - web-hooks in pagure and how to use them. diff --git a/doc/theming.rst b/doc/theming.rst deleted file mode 100644 index 961b4ab..0000000 --- a/doc/theming.rst +++ /dev/null @@ -1,81 +0,0 @@ -Theme your pagure -================= - -Pagure via `flask-multistatic `_ -offers the possibility to override the default theme allowing to customize -the style of your instance. - -By default pagure looks for its templates and static files in the folders -``pagure/templates`` and ``pagure/static``, but you can ask pagure to look -for templates and static files in another folder. - -By specifying the configuration keys ``THEME_TEMPLATE_FOLDER`` and -``THEME_STATIC_FOLDER`` in pagure's configuration file, you tell pagure to -look for templates and static files first in these folders, then in its -usual folders. - - -.. note: The principal is that pagure will look in the folder specified in - the configuration file first and then in its usual folder, so the - **file names must be identical**. - -Example -------- - -Let's take an example, you wish to replace the pagure logo at the top right -of all the pages. - -This logo is part of the ``master.html`` template which all pages inherit -from. So what you want to do is replace this ``master.html`` by your own. - -* First, create the folder where your templates and static files will be stored: - -:: - - mkdir /var/www/mypaguretheme/templates - mkdir /var/www/mypaguretheme/static - -* Place your own logo in the static folder - -:: - - cp /path/to/your/my-logo.png /var/www/mypaguretheme/static - -* Place in there the original ``master.html`` - -:: - - cp /path/to/original/pagure/templates/master.html /var/www/mypaguretheme/templates - -* Edit it and replace the url pointing to the pagure logo (around line 27) - -:: - - - `_ -is provided as part of the sources of `flask-multistatic `_. diff --git a/doc/ticket_templates.rst b/doc/ticket_templates.rst deleted file mode 100644 index 9c45651..0000000 --- a/doc/ticket_templates.rst +++ /dev/null @@ -1,77 +0,0 @@ -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. diff --git a/doc/upgrade_db.rst b/doc/upgrade_db.rst deleted file mode 100644 index 6c3ebe3..0000000 --- a/doc/upgrade_db.rst +++ /dev/null @@ -1,48 +0,0 @@ -Upgrade a database -================== - - -Database schema migration are handled in two ways: - -* New tables - -For this we simply rely on the ``createdb`` script used when creating the -database the first time. - -* Changes to existing tables - -For changes to existing tables, we rely on `Alembic `_. -This allows us to do upgrade and downgrade of schema migration, kind of like -one would do commits in a system like git. - -To upgrade the database to the latest version simply run: -:: - - alembic upgrade head - -This may fail for different reasons: - -* The change was already made in the database - -This can be because the version of the database schema saved is incorrect. -It can be debugged using the following commands: - - * Find the current revision: ``alembic current`` - * See the entire history: ``alembic history`` - -Once the revision at which your database should be is found (in the history) -you can declare that your database is at this given revision using: -``alembic stamp ``. - -Eventually, if you do not know where your database is or should be, you can -do an iterative process stamping the database for every revision, one by one -trying everytime to ``alembic upgrade`` until it works. - -* The database used does not support some of the changes - -SQLite is handy for development but does not support all the features of a -real database server. Upgrading a SQLite database might therefore not work, -depending on the changes done. - -In some cases, if you are using a SQLite database, you will have to destroy -it and create a new one. diff --git a/doc/usage.rst b/doc/usage.rst index 9ee08e4..7ac0b3f 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -38,11 +38,11 @@ Contents: .. toctree:: :maxdepth: 2 - first_steps - project_settings - using_doc - using_webhooks - ticket_templates - pr_custom_page - theming - upgrade_db + usage/first_steps + usage/project_settings + usage/using_doc + usage/using_webhooks + usage/ticket_templates + usage/pr_custom_page + usage/theming + usage/upgrade_db diff --git a/doc/usage/first_steps.rst b/doc/usage/first_steps.rst new file mode 100644 index 0000000..cdb42e4 --- /dev/null +++ b/doc/usage/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 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. + +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 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! diff --git a/doc/usage/pr_custom_page.rst b/doc/usage/pr_custom_page.rst new file mode 100644 index 0000000..86aa195 --- /dev/null +++ b/doc/usage/pr_custom_page.rst @@ -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. diff --git a/doc/usage/project_settings.rst b/doc/usage/project_settings.rst new file mode 100644 index 0000000..2350a0c --- /dev/null +++ b/doc/usage/project_settings.rst @@ -0,0 +1,145 @@ +Project settings +================ + +Each project have a number of options that can be tweaked in the settings +page of the project which is accessible to the person having full commits +to the project. + +This page presents the different settings and there effect. + + +`Activate always merge` +------------------------ + +This boolean enables or disables always making a merge commit when merging +a pull-request. + +When merging a pull-request in pagure there are three states: + +* fast-forward: when the commits in the pull-request can be fast-forwarded +pagure signals it and just fast-forward the commit, keeping the history linear. +* merge: when the commits in the pull-request cannot be merged without a merge +commit, pagure signals it and performs this merge commit. +* conflicts: when the commits in the pull-request cannot be merged at all +automatically due to one or more conflicts. Then pagure signals it and prevent +merging. + +If the `Activate always merge` option is on, then the `fast-forward` option +above is disabled in favor of the `merge` option. + + +`Activate comment editing` +-------------------------- + +This boolean enables or disables editing comments. + +After commenting on a ticket or a pull-request, the admins of the project +and the author of the comment may be allowed to edit the comment. +This allows them to adjust the wording or the style as they wish. + +.. note:: notification about a comment is only sent once with the original + text, changes performed later will not trigger a new notification. + +Some project may not want to allow editing comments after they were posted +and this setting allows turning it on or off. + + +`Activate Enforce signed-off commits in pull-request` +----------------------------------------------------- + +This boolean enables or disables checking for a 'Signed-off-by' line (case +insensitive) in the commit messages of the pull-requests. + +If this line is missing, pagure will display a message near the `Merge` +button, allowing project admin to request the PR to be updated. + +.. note:: This setting does not prevent commits without this 'signed-off-by' + line to be pushed directly, it only work at the pull-request level. + + +`Activate issue tracker` +------------------------ + +This boolean simply enables or disables the issue tracker for the project. +So if you are tracking your ticket on a different system, you can simply +disable reporting issue on pagure by un-checking this option. + + +`Activate Minimum score to merge pull-request` +---------------------------------------------- + +This option can be used for project wishing to enforce having a minimum +number of people reviewing a pull-request before it can be merged. + +If this option is enabled, anyone can vote in favor or against a pull-request +and the sum of the votes in favor minus the sum of the votes againsts give +the pull-request a score that should be equal or great to the value +entered in this option for the pull-request to be allowed to be merged. + +.. note:: Only the main comments (ie: not in-line) are taken into account + to calculate the score of the pull-request. + +To vote in favor of a pull-request, use either: +* ``+1`` +* ``:thumbsup:`` + +To vote against a pull-request, use either: +* ``-1`` +* ``:thumbsdown:`` + +.. note:: Pull-Request reaching the minimum score are not automatically merged + +.. note:: Anyone can vote on the pull-request, not only the contributors. + + +`Activate Only assignee can merge pull-request` +----------------------------------------------- + +This option can be used for project wishing to institute a strong review +workflow where pull-request are first assigned then merged. + +If this option is enabled, only the person assigned to the pull-request +can merge it. + + +`Activate project documentation` +-------------------------------- + +Pagure offers the option to have a git repository specific for the +documentation of the project. + +This repository is then accessible under the ``Docs`` tab in the menu of the +project. + +If you prefer to store your documentation elsewhere or maybe even within +the sources of the project, you can disable the ``Docs`` tab by un-checking +this option. + + +`Activate pull requests` +------------------------ + +Pagure offers the option to fork a project, make changes to it and then ask +the developer to merge these changes into the project. This is similar to +the pull-request mechanism on GitHub or GitLab. + +However, some projects may prefer receiving patches by email on their list +or via another hosting plateform or simply do not wish to use the +pull-request mechanism at all. Un-checking this option will therefore +prevent anyone from opening a pull-request against this project. + +.. note:: disabling pull-requests does *not* disable forking the projects. + + +`Activate Web-hooks` +-------------------- + +Pagure offers the option of sending notification about event happening on a +project via [web-hooks|https://en.wikipedia.org/wiki/Webhook]. This option +is off by default and can be turned on for a pagure instance in its +configuration file. + +The URL of the web-hooks can be entered in this field. + +.. note:: See the ``notifications`` documentation to learn more about + web-hooks in pagure and how to use them. diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst new file mode 100644 index 0000000..961b4ab --- /dev/null +++ b/doc/usage/theming.rst @@ -0,0 +1,81 @@ +Theme your pagure +================= + +Pagure via `flask-multistatic `_ +offers the possibility to override the default theme allowing to customize +the style of your instance. + +By default pagure looks for its templates and static files in the folders +``pagure/templates`` and ``pagure/static``, but you can ask pagure to look +for templates and static files in another folder. + +By specifying the configuration keys ``THEME_TEMPLATE_FOLDER`` and +``THEME_STATIC_FOLDER`` in pagure's configuration file, you tell pagure to +look for templates and static files first in these folders, then in its +usual folders. + + +.. note: The principal is that pagure will look in the folder specified in + the configuration file first and then in its usual folder, so the + **file names must be identical**. + +Example +------- + +Let's take an example, you wish to replace the pagure logo at the top right +of all the pages. + +This logo is part of the ``master.html`` template which all pages inherit +from. So what you want to do is replace this ``master.html`` by your own. + +* First, create the folder where your templates and static files will be stored: + +:: + + mkdir /var/www/mypaguretheme/templates + mkdir /var/www/mypaguretheme/static + +* Place your own logo in the static folder + +:: + + cp /path/to/your/my-logo.png /var/www/mypaguretheme/static + +* Place in there the original ``master.html`` + +:: + + cp /path/to/original/pagure/templates/master.html /var/www/mypaguretheme/templates + +* Edit it and replace the url pointing to the pagure logo (around line 27) + +:: + + - `_ +is provided as part of the sources of `flask-multistatic `_. diff --git a/doc/usage/ticket_templates.rst b/doc/usage/ticket_templates.rst new file mode 100644 index 0000000..9c45651 --- /dev/null +++ b/doc/usage/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 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. diff --git a/doc/usage/upgrade_db.rst b/doc/usage/upgrade_db.rst new file mode 100644 index 0000000..6c3ebe3 --- /dev/null +++ b/doc/usage/upgrade_db.rst @@ -0,0 +1,48 @@ +Upgrade a database +================== + + +Database schema migration are handled in two ways: + +* New tables + +For this we simply rely on the ``createdb`` script used when creating the +database the first time. + +* Changes to existing tables + +For changes to existing tables, we rely on `Alembic `_. +This allows us to do upgrade and downgrade of schema migration, kind of like +one would do commits in a system like git. + +To upgrade the database to the latest version simply run: +:: + + alembic upgrade head + +This may fail for different reasons: + +* The change was already made in the database + +This can be because the version of the database schema saved is incorrect. +It can be debugged using the following commands: + + * Find the current revision: ``alembic current`` + * See the entire history: ``alembic history`` + +Once the revision at which your database should be is found (in the history) +you can declare that your database is at this given revision using: +``alembic stamp ``. + +Eventually, if you do not know where your database is or should be, you can +do an iterative process stamping the database for every revision, one by one +trying everytime to ``alembic upgrade`` until it works. + +* The database used does not support some of the changes + +SQLite is handy for development but does not support all the features of a +real database server. Upgrading a SQLite database might therefore not work, +depending on the changes done. + +In some cases, if you are using a SQLite database, you will have to destroy +it and create a new one. diff --git a/doc/usage/using_doc.rst b/doc/usage/using_doc.rst new file mode 100644 index 0000000..d56535d --- /dev/null +++ b/doc/usage/using_doc.rst @@ -0,0 +1,108 @@ +Using the doc repository of your project +======================================== + +In this section of the documentation, we are interested in the doc repository. + +The doc repository is a simple git repo, whose content will appear under the +`Docs` tab in pagure and on https://docs.pagure.org//. + +There are a few ways you can put your documentation in this repo: + +* Simple text files + +Pagure will display them as plain text. If one of these is named ``index`` +it will be presented as the front page. + +* rst or markdown files + +Pagure will convert them to html on the fly and display them as such. +The rst files must end with `.rst` and the markdown ones must end with +``.mk``, ``.md`` or simply ``.markdown``. + +* html files + +Pagure will simply show them as such. + + +.. note: By default the `Docs` tab in the project's menu is disabled, you + will have to visit the project's settings page and turn it on + in the ``Project options`` section. + + +Example +------- + +Pagure's documentation is kept in pagure's sources, in the `doc` folder there. +You can see it at: `https://pagure.io/pagure/blob/master/f/doc +`_. This doc can be built with +`sphinx `_ to make it html and prettier. + +The built documentation is available at: `https://docs.pagure.org/pagure/ +`_. + +This is how it is built/updated: + +* Clone pagure's sources:: + + git clone https://pagure.io/docs/pagure.git + +* Move into its doc folder:: + + cd pagure/doc + +* Build the doc:: + + make html + +* Clone pagure's doc repository:: + + git clone ssh://git@pagure.io/docs/pagure.git + +* Copy the result of sphinx's build to the doc repo:: + + cp -r _build/html/* pagure/ + +* Go into the doc repo and update it:: + + cd pagure + git add . + git commit -am "Update documentation" + git push + +* Clean the sources:: + + cd .. + rm -rf pagure # remove the doc repo + rm -rf _build # remove the output from the sphinx's build + + +To make things simpler, the following script (name `update_doc.sh`) can be +used: + +:: + + #!/bin/bash + + make html + + git clone "ssh://git@pagure.io/docs/$1.git" + cp -r _build/html/* $1/ + ( + cd $1 + git add . + git commit -av + git push + ) + + rm -rfI _build + rm -rfI $1 + +It can be used by running `update_doc.sh ` from within the folder +containing the doc. + +So for pagure it would be something like: + +:: + + cd pagure/doc + update_doc.sh pagure diff --git a/doc/usage/using_webhooks.rst b/doc/usage/using_webhooks.rst new file mode 100644 index 0000000..0040b1e --- /dev/null +++ b/doc/usage/using_webhooks.rst @@ -0,0 +1,47 @@ +Using web-hooks +=============== + +Web-hooks are a notification system that could be compared to a callback. +Basically, pagure will make a HTTP POST request to one or more third party +server/application with information about what is or just happened. + +To set-up a web-hook, simply go to the settings page of your project and +enter the URL to the server that will receive the notifications. + +In the settings page is also present a web-hook key which is used by the +server to sign the message sent and which you can use to ensure the +notifications received are coming from the right source. + +Each POST request made contains two specific headers: + +:: + + X-Pagure-Topic + X-Pagure-Signature + + +``X-Pagure-Topic`` is a global header giving a clue about the type of action +that just occured. For example ``issue.edit``. + + +``X-Pagure-Signature`` contains the signature of the message allowing to +check that the message comes from pagure. + + +Pagure relies on ``hmac`` to sign the content of its messages. If you want +to validate the message, in python, you can do something like the following: + +:: + + import hmac + import hashlib + + payload = # content you received in the POST request + headers = # headers of the POST request + project_web_hook_key = # private web-hook key of the project + + hashhex = hmac.new( + str(project_web_hook_key), payload, hashlib.sha1).hexdigest() + + if hashhex != headers.get('X-Pagure-Signature'): + raise Exception('Message received with an invalid signature') diff --git a/doc/using_doc.rst b/doc/using_doc.rst deleted file mode 100644 index d56535d..0000000 --- a/doc/using_doc.rst +++ /dev/null @@ -1,108 +0,0 @@ -Using the doc repository of your project -======================================== - -In this section of the documentation, we are interested in the doc repository. - -The doc repository is a simple git repo, whose content will appear under the -`Docs` tab in pagure and on https://docs.pagure.org//. - -There are a few ways you can put your documentation in this repo: - -* Simple text files - -Pagure will display them as plain text. If one of these is named ``index`` -it will be presented as the front page. - -* rst or markdown files - -Pagure will convert them to html on the fly and display them as such. -The rst files must end with `.rst` and the markdown ones must end with -``.mk``, ``.md`` or simply ``.markdown``. - -* html files - -Pagure will simply show them as such. - - -.. note: By default the `Docs` tab in the project's menu is disabled, you - will have to visit the project's settings page and turn it on - in the ``Project options`` section. - - -Example -------- - -Pagure's documentation is kept in pagure's sources, in the `doc` folder there. -You can see it at: `https://pagure.io/pagure/blob/master/f/doc -`_. This doc can be built with -`sphinx `_ to make it html and prettier. - -The built documentation is available at: `https://docs.pagure.org/pagure/ -`_. - -This is how it is built/updated: - -* Clone pagure's sources:: - - git clone https://pagure.io/docs/pagure.git - -* Move into its doc folder:: - - cd pagure/doc - -* Build the doc:: - - make html - -* Clone pagure's doc repository:: - - git clone ssh://git@pagure.io/docs/pagure.git - -* Copy the result of sphinx's build to the doc repo:: - - cp -r _build/html/* pagure/ - -* Go into the doc repo and update it:: - - cd pagure - git add . - git commit -am "Update documentation" - git push - -* Clean the sources:: - - cd .. - rm -rf pagure # remove the doc repo - rm -rf _build # remove the output from the sphinx's build - - -To make things simpler, the following script (name `update_doc.sh`) can be -used: - -:: - - #!/bin/bash - - make html - - git clone "ssh://git@pagure.io/docs/$1.git" - cp -r _build/html/* $1/ - ( - cd $1 - git add . - git commit -av - git push - ) - - rm -rfI _build - rm -rfI $1 - -It can be used by running `update_doc.sh ` from within the folder -containing the doc. - -So for pagure it would be something like: - -:: - - cd pagure/doc - update_doc.sh pagure diff --git a/doc/using_webhooks.rst b/doc/using_webhooks.rst deleted file mode 100644 index 0040b1e..0000000 --- a/doc/using_webhooks.rst +++ /dev/null @@ -1,47 +0,0 @@ -Using web-hooks -=============== - -Web-hooks are a notification system that could be compared to a callback. -Basically, pagure will make a HTTP POST request to one or more third party -server/application with information about what is or just happened. - -To set-up a web-hook, simply go to the settings page of your project and -enter the URL to the server that will receive the notifications. - -In the settings page is also present a web-hook key which is used by the -server to sign the message sent and which you can use to ensure the -notifications received are coming from the right source. - -Each POST request made contains two specific headers: - -:: - - X-Pagure-Topic - X-Pagure-Signature - - -``X-Pagure-Topic`` is a global header giving a clue about the type of action -that just occured. For example ``issue.edit``. - - -``X-Pagure-Signature`` contains the signature of the message allowing to -check that the message comes from pagure. - - -Pagure relies on ``hmac`` to sign the content of its messages. If you want -to validate the message, in python, you can do something like the following: - -:: - - import hmac - import hashlib - - payload = # content you received in the POST request - headers = # headers of the POST request - project_web_hook_key = # private web-hook key of the project - - hashhex = hmac.new( - str(project_web_hook_key), payload, hashlib.sha1).hexdigest() - - if hashhex != headers.get('X-Pagure-Signature'): - raise Exception('Message received with an invalid signature') From 67f9383dabfc130935f9d6d469f8dcd10e5154d5 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 19 2016 08:40:23 +0000 Subject: [PATCH 18/22] Adjust the documentation based on @puiterwijk's feedback --- diff --git a/doc/install.rst b/doc/install.rst index c1269ce..4b2e3bd 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -245,8 +245,8 @@ You can save the current revision in the database using the following command: alembic stamp $(alembic heads |awk '{ print $1 }') The ``cd /etc/pagure`` is needed as the command must be run in the folder -where is the file ``alembic.ini``. This file contains two important -information: +where the file ``alembic.ini`` is. This file contains two important pieces +of information: * ``sqlalchemy.url`` which is the URL used to connect to the database, likely the same URL as the one in ``pagure.cfg``. diff --git a/doc/usage.rst b/doc/usage.rst index 7ac0b3f..09e7587 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -23,13 +23,7 @@ overview page of the project. On the menu on the right side, there is a menu you will be given the URLs to the other three git repos. Each section correspond to one of the four git repositories created for each -project: - -* A git repository containing the source code, displayed in the main section - of the pagure project. -* A git repository for the documentation -* A git repository for the issues and their metadata -* A git repository for the metadata for pull-requests +project. diff --git a/doc/usage/using_webhooks.rst b/doc/usage/using_webhooks.rst index 0040b1e..4e1d4ae 100644 --- a/doc/usage/using_webhooks.rst +++ b/doc/usage/using_webhooks.rst @@ -6,11 +6,11 @@ Basically, pagure will make a HTTP POST request to one or more third party server/application with information about what is or just happened. To set-up a web-hook, simply go to the settings page of your project and -enter the URL to the server that will receive the notifications. +enter the URL to the server/endpoint that will receive the notifications. -In the settings page is also present a web-hook key which is used by the -server to sign the message sent and which you can use to ensure the -notifications received are coming from the right source. +There is, in the settings page, a web-hook key which is used by the +server (here pagure) to sign the message sent and which you can use to +ensure the notifications received are coming from the right source. Each POST request made contains two specific headers: From d5f7e1cf1b40630d498469b6cb59e77c3a3789a2 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 19 2016 08:40:27 +0000 Subject: [PATCH 19/22] Link to the fedmsg doc on pagure for topics and payload examples --- diff --git a/doc/usage/using_webhooks.rst b/doc/usage/using_webhooks.rst index 4e1d4ae..721a7f4 100644 --- a/doc/usage/using_webhooks.rst +++ b/doc/usage/using_webhooks.rst @@ -45,3 +45,10 @@ to validate the message, in python, you can do something like the following: if hashhex != headers.get('X-Pagure-Signature'): raise Exception('Message received with an invalid signature') + + +The notifications sent via web-hooks have the same payload as what is sent +via `fedmsg `_. Therefore, the list of +pagure topics as well as example messages can be found in the +`fedmsg documentation about pagure +`_ From fb562f036794c82832b8fb98f2d1eb25232c4474 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 19 2016 09:03:55 +0000 Subject: [PATCH 20/22] Document that the headers are un-signed and shouldn't be blindly trusted --- diff --git a/doc/usage/using_webhooks.rst b/doc/usage/using_webhooks.rst index 721a7f4..edb68e8 100644 --- a/doc/usage/using_webhooks.rst +++ b/doc/usage/using_webhooks.rst @@ -27,6 +27,9 @@ that just occured. For example ``issue.edit``. ``X-Pagure-Signature`` contains the signature of the message allowing to check that the message comes from pagure. +.. note:: These headers are present for convenience only, they are not signed + and therefore should not be trusted. Rely on the payload after + checking the signature to make any decision. Pagure relies on ``hmac`` to sign the content of its messages. If you want to validate the message, in python, you can do something like the following: From 4ffa5fa573e8023450f7c454b7836d2c30be6dca Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 19 2016 09:18:23 +0000 Subject: [PATCH 21/22] Add a warning about using sqlite in production (not advised at all) --- diff --git a/doc/install.rst b/doc/install.rst index 4b2e3bd..7490087 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -230,6 +230,11 @@ For example: This will tell ``/usr/share/pagure/pagure_createdb.py`` to use the database information specified in the file ``/etc/pagure/pagure.cfg``. +.. warning:: Pagure's default configuration is using sqlite. This is fine + for development purpose but not for production use as sqlite does + not support all the operations needed when updating the database + schema. Do use PostgreSQL, MySQL or MariaDB in production. + * Stamp the alembic revision For changes to existing tables, we rely on `Alembic `_. From 70d7071c4bb72341d8de0fcc54a7514efcb144d2 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Apr 19 2016 09:19:23 +0000 Subject: [PATCH 22/22] Turn the note about unsigned header into a warning --- diff --git a/doc/usage/using_webhooks.rst b/doc/usage/using_webhooks.rst index edb68e8..7e48058 100644 --- a/doc/usage/using_webhooks.rst +++ b/doc/usage/using_webhooks.rst @@ -27,9 +27,9 @@ that just occured. For example ``issue.edit``. ``X-Pagure-Signature`` contains the signature of the message allowing to check that the message comes from pagure. -.. note:: These headers are present for convenience only, they are not signed - and therefore should not be trusted. Rely on the payload after - checking the signature to make any decision. +.. warning:: These headers are present for convenience only, they are not + signed and therefore should not be trusted. Rely on the payload + after checking the signature to make any decision. Pagure relies on ``hmac`` to sign the content of its messages. If you want to validate the message, in python, you can do something like the following: