Blame doc/usage/project_settings.rst

Pierre-Yves Chibon abdeee
Project settings
Pierre-Yves Chibon abdeee
================
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
Each project have a number of options that can be tweaked in the settings
Pierre-Yves Chibon abdeee
page of the project which is accessible to the person having full commits
Pierre-Yves Chibon abdeee
to the project.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
This page presents the different settings and there effect.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
jingjing 6b2e3d
`Always merge`
Pierre-Yves Chibon 694168
------------------------
Pierre-Yves Chibon 694168
René Genz ec0022
This Boolean enables or disables always making a merge commit when merging
Pierre-Yves Chibon 694168
a pull-request.
Pierre-Yves Chibon 694168
Pierre-Yves Chibon 694168
When merging a pull-request in pagure there are three states:
Pierre-Yves Chibon 694168
Pierre-Yves Chibon 694168
* fast-forward: when the commits in the pull-request can be fast-forwarded
Farhaan Bukhsh c73dc4
  pagure signals it and just fast-forward the commit, keeping the history linear.
Farhaan Bukhsh c73dc4
Pierre-Yves Chibon 694168
* merge: when the commits in the pull-request cannot be merged without a merge
Farhaan Bukhsh c73dc4
  commit, pagure signals it and performs this merge commit.
Farhaan Bukhsh c73dc4
Pierre-Yves Chibon 694168
* conflicts: when the commits in the pull-request cannot be merged at all
Farhaan Bukhsh c73dc4
  automatically due to one or more conflicts. Then pagure signals it and prevent
Farhaan Bukhsh c73dc4
  merging.
Pierre-Yves Chibon 694168
jingjing 6b2e3d
If the `Always merge` option is on, then the `fast-forward` option
Pierre-Yves Chibon 694168
above is disabled in favor of the `merge` option.
Pierre-Yves Chibon 694168
Pierre-Yves Chibon 694168
jingjing 6b2e3d
`Comment editing`
Pierre-Yves Chibon 91c8e5
--------------------------
Pierre-Yves Chibon 91c8e5
René Genz ec0022
This Boolean enables or disables editing comments.
Pierre-Yves Chibon 91c8e5
Pierre-Yves Chibon 91c8e5
After commenting on a ticket or a pull-request, the admins of the project
Pierre-Yves Chibon 91c8e5
and the author of the comment may be allowed to edit the comment.
Pierre-Yves Chibon 91c8e5
This allows them to adjust the wording or the style as they wish.
Pierre-Yves Chibon 91c8e5
Pierre-Yves Chibon 91c8e5
.. note:: notification about a comment is only sent once with the original
Pierre-Yves Chibon 91c8e5
          text, changes performed later will not trigger a new notification.
Pierre-Yves Chibon 91c8e5
Pierre-Yves Chibon 91c8e5
Some project may not want to allow editing comments after they were posted
Pierre-Yves Chibon 91c8e5
and this setting allows turning it on or off.
Pierre-Yves Chibon 91c8e5
Pierre-Yves Chibon 91c8e5
jingjing 6b2e3d
`Enforce signed-off commits in pull-request`
Pierre-Yves Chibon d665ec
-----------------------------------------------------
Pierre-Yves Chibon d665ec
René Genz ec0022
This Boolean enables or disables checking for a 'Signed-off-by' line (case
Pierre-Yves Chibon d665ec
insensitive) in the commit messages of the pull-requests.
Pierre-Yves Chibon d665ec
Pierre-Yves Chibon d665ec
If this line is missing, pagure will display a message near the `Merge`
Pierre-Yves Chibon d665ec
button, allowing project admin to request the PR to be updated.
Pierre-Yves Chibon d665ec
Pierre-Yves Chibon d665ec
.. note:: This setting does not prevent commits without this 'signed-off-by'
Pierre-Yves Chibon d665ec
          line to be pushed directly, it only work at the pull-request level.
Pierre-Yves Chibon d665ec
Pierre-Yves Chibon d665ec
jingjing 6b2e3d
`Issue tracker`
Pierre-Yves Chibon 36c7fc
------------------------
Pierre-Yves Chibon abdeee
René Genz ec0022
This Boolean simply enables or disables the issue tracker for the project.
Pierre-Yves Chibon abdeee
So if you are tracking your ticket on a different system, you can simply
Pierre-Yves Chibon abdeee
disable reporting issue on pagure by un-checking this option.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
jingjing 6b2e3d
`Minimum score to merge pull-request`
Pierre-Yves Chibon 82f2ff
----------------------------------------------
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
This option can be used for project wishing to enforce having a minimum
Pierre-Yves Chibon 82f2ff
number of people reviewing a pull-request before it can be merged.
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
If this option is enabled, anyone can vote in favor or against a pull-request
René Genz 520020
and the sum of the votes in favor minus the sum of the votes against give
René Genz 520020
the pull-request a score that should be equal or greater than the value
Pierre-Yves Chibon 82f2ff
entered in this option for the pull-request to be allowed to be merged.
Pierre-Yves Chibon 82f2ff
René Genz ec0022
.. note:: Only the main comments (i.e.: not in-line) are taken into account
Pierre-Yves Chibon 82f2ff
          to calculate the score of the pull-request.
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
To vote in favor of a pull-request, use either:
Pierre-Yves Chibon 82f2ff
* ``+1``
Pierre-Yves Chibon 82f2ff
* ``:thumbsup:``
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
To vote against a pull-request, use either:
Pierre-Yves Chibon 82f2ff
* ``-1``
Pierre-Yves Chibon 82f2ff
* ``:thumbsdown:``
Pierre-Yves Chibon 82f2ff
Fabien Boucher ad5f8b
.. note:: Pull-Request not reaching the minimum score are not automatically
Fabien Boucher ad5f8b
          merged
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
.. note:: Anyone can vote on the pull-request, not only the contributors.
Pierre-Yves Chibon 82f2ff
Fabien Boucher ad5f8b
.. note:: Only one vote per person is taken into account to compute the final
Fabien Boucher ad5f8b
          score.
Fabien Boucher ad5f8b
Pierre-Yves Chibon 82f2ff
jingjing 6b2e3d
`Only assignee can merge pull-request`
Pierre-Yves Chibon 82f2ff
-----------------------------------------------
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
This option can be used for project wishing to institute a strong review
Pierre-Yves Chibon 82f2ff
workflow where pull-request are first assigned then merged.
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
If this option is enabled, only the person assigned to the pull-request
Pierre-Yves Chibon 82f2ff
can merge it.
Pierre-Yves Chibon 82f2ff
Pierre-Yves Chibon 82f2ff
jingjing 6b2e3d
`Project documentation`
Pierre-Yves Chibon 36c7fc
--------------------------------
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
Pagure offers the option to have a git repository specific for the
Pierre-Yves Chibon abdeee
documentation of the project.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
This repository is then accessible under the ``Docs`` tab in the menu of the
Pierre-Yves Chibon abdeee
project.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
If you prefer to store your documentation elsewhere or maybe even within
Pierre-Yves Chibon abdeee
the sources of the project, you can disable the ``Docs`` tab by un-checking
Pierre-Yves Chibon abdeee
this option.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
jingjing 6b2e3d
`Pull requests`
Pierre-Yves Chibon 36c7fc
------------------------
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
Pagure offers the option to fork a project, make changes to it and then ask
Pierre-Yves Chibon abdeee
the developer to merge these changes into the project. This is similar to
Pierre-Yves Chibon abdeee
the pull-request mechanism on GitHub or GitLab.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
However, some projects may prefer receiving patches by email on their list
René Genz ec0022
or via another hosting platform or simply do not wish to use the
Pierre-Yves Chibon abdeee
pull-request mechanism at all. Un-checking this option will therefore
Pierre-Yves Chibon abdeee
prevent anyone from opening a pull-request against this project.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
.. note:: disabling pull-requests does *not* disable forking the projects.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
jingjing 6b2e3d
`Web-hooks`
Pierre-Yves Chibon 36c7fc
--------------------
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon 9c66ac
Pagure offers the option of sending notification about event happening on a
Pierre-Yves Chibon 9c66ac
project via [web-hooks|https://en.wikipedia.org/wiki/Webhook]. This option
Pierre-Yves Chibon 9c66ac
is off by default and can be turned on for a pagure instance in its
Pierre-Yves Chibon 9c66ac
configuration file.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
The URL of the web-hooks can be entered in this field.
Pierre-Yves Chibon abdeee
Pierre-Yves Chibon abdeee
.. note:: See the ``notifications`` documentation to learn more about
Pierre-Yves Chibon abdeee
          web-hooks in pagure and how to use them.
Mark Reynolds d306af
Mark Reynolds d306af
`Tags`
Mark Reynolds d306af
------
Mark Reynolds d306af
Mark Reynolds d306af
Pagure allows you to define "tags" that can be added to Issues.  Tags are
Mark Reynolds d306af
unique to each project, and they can only be defined in the project
Mark Reynolds d306af
settings page.  The Tag color can also be customized for a more robust
Mark Reynolds d306af
visual representation of the tag.
Mark Reynolds d306af
Patrick Uiterwijk 19b63c
`Deploy keys`
Patrick Uiterwijk 19b63c
-------------
Mark Reynolds d306af
Patrick Uiterwijk 19b63c
Deploy keys are SSH keys that have access to pull/push only to a single
Patrick Uiterwijk 19b63c
project.
Patrick Uiterwijk 19b63c
Upon creation, admins can determine whether this particular key has read/write
Patrick Uiterwijk 19b63c
access or read-only.