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')