diff --git a/docs/conf.py b/docs/conf.py
index da1c47927..607f4f3b0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -71,6 +71,7 @@
html_static_path = ["_static"]
html_theme = "pydata_sphinx_theme"
html_theme_options = {
+ "announcement": "Until further notice, maintainers alone are unable to respond to the high volume of new pull requests.
See Conduct a peer review instead of opening a new pull request.", # noqa: E501
"icon_links": [
{
"name": "GitHub",
diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst
index 074e7ba2f..bdcd39476 100644
--- a/docs/contribute/index.rst
+++ b/docs/contribute/index.rst
@@ -2,6 +2,11 @@
Contribute
==========
+.. important::
+
+ Until further notice, maintainers alone are unable to respond to the high volume of new pull requests.
+ To help improve this situation, it's strongly recommended that you :ref:`conduct-a-peer-review` instead of opening a new pull request.
+
This guide describes how to contribute to icalendar.
A key purpose around icalendar is to foster a warm and welcoming space for people to learn, grow, and contribute.
@@ -30,8 +35,7 @@ Triage and review
- Comment on and resolve issues.
- Triage open issues and `pull requests `_.
-- Review, comment on, and make suggestions to change a pull request.
- See the GitHub documentation `Reviewing proposed changes in a pull request `_.
+- :ref:`conduct-a-peer-review`.
- Reproduce an issue and add a comment with your findings.
Documentation
@@ -148,10 +152,12 @@ If you use AI in your work:
- You shall be held accountable for your AI-generated content.
+.. _ai-abuse:
+
AI abuse
````````
-You may not abuse AI to generate a pull request that is disruptive to the icalendar community or does not adhere to :ref:`responsible-ai-use` described in the previous subsection.
+You may not abuse AI to generate a pull request, issue, or comment that is disruptive to the icalendar community or does not adhere to :ref:`responsible-ai-use` described in the previous subsection.
Examples of such abuse and irresponsible use include the following actions.
- You claim no responsibility for the output of AI generated content.
@@ -159,6 +165,9 @@ Examples of such abuse and irresponsible use include the following actions.
- Your pull request plagiarizes copyrighted or other material to which you have no legal claim.
- You ignore or don't respond to feedback.
- The GitHub account is itself an AI agent.
+- Never copy-paste AI generated content verbatim.
+ It's verbose, unhelpful, and wastes the readers' time.
+- You cite anything that is recorded or duplicates features in the GitHub user interface, including test results and counts in CI checks, code changes that can be seen in the diff viewer, and commit messages.
Report suspected violations
@@ -170,6 +179,71 @@ The maintainers may close pull requests without providing feedback that they dee
The maintainers may also take further action, including suspend, ban, or report GitHub users, as described in Python Calendaring Ecosystem's `Code of Conduct `_.
+.. _conduct-a-peer-review:
+
+Conduct a peer review
+---------------------
+
+.. important::
+
+ Until further notice, maintainers alone are unable to respond to the high volume of new pull requests.
+ Read this section for information about how you can help improve the situation.
+
+A peer review is when you look at an open pull request of another contributor, and make comments and suggestions to improve its quality.
+You'll help your colleagues, learn from one another, and gain valuable communication and collaboration skills that every programming job requires.
+It will also help maintainers handle high priority items in a timely manner, such as addressing security reports, making releases, and conducting final code and documentation reviews.
+
+
+Good peer review
+````````````````
+
+A good peer review includes the following steps.
+
+.. steps::
+
+ .. step::
+
+ Find an open pull request that interests you, and open it.
+
+ .. step::
+
+ Click its :guilabel:`Files changed` tab.
+
+ .. step::
+
+ Add questions, comments, or suggestions.
+ You can also provide code to replace their change.
+ See the GitHub documentation `Starting a review `_.
+
+ .. step::
+
+ Ensure that the change log entry complies with :ref:`change-log`.
+
+ .. step::
+
+ Ensure that the documentation renders correctly—including the change log, docstrings, and narrative documentation—according to :ref:`pull-request-previews`.
+
+
+If you use AI, follow our :ref:`artificial-intelligence-policy`.
+Thoughtful suggestions are especially helpful.
+
+.. note::
+
+ Some IDEs have pull request interfaces that replicate the features of GitHub's web interface.
+
+
+Poor peer review
+````````````````
+
+A poor peer review is unwanted and unnecessary.
+Examples of poor peer reviews include the following.
+
+- Creating a single comment in the pull request's :guilabel:`Conversation` tab.
+- Copy paste AI-generated content without you reviewing and editing it.
+ See :ref:`responsible-ai-use`.
+- Restating the obvious.
+
+
.. _issue-requirements:
Issue requirements
diff --git a/news/+peer-review.documentation b/news/+peer-review.documentation
new file mode 100644
index 000000000..97f7bcde4
--- /dev/null
+++ b/news/+peer-review.documentation
@@ -0,0 +1 @@
+Documented what is a peer review, both good and bad, and how to conduct one. Added an admonition and a site-wide announcement about our inability to handle the volume of new pull requests and how contributors can help. :user:`stevepiercy`