Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br>See <a href='https://icalendar.readthedocs.io/en/latest/contribute/index.html#conduct-a-peer-review'>Conduct a peer review</a> instead of opening a new pull request.", # noqa: E501
"icon_links": [
{
"name": "GitHub",
Expand Down
80 changes: 77 additions & 3 deletions docs/contribute/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -30,8 +35,7 @@ Triage and review

- Comment on and resolve issues.
- Triage open issues and `pull requests <https://github.com/PyCalendar/icalendar/pulls>`_.
- Review, comment on, and make suggestions to change a pull request.
See the GitHub documentation `Reviewing proposed changes in a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request>`_.
- :ref:`conduct-a-peer-review`.
- Reproduce an issue and add a comment with your findings.

Documentation
Expand Down Expand Up @@ -148,17 +152,22 @@ 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.
- Your pull request demonstrates no understanding or thought whatsoever to solve an issue.
- 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
Expand All @@ -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 <https://pycal.org/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 <https://docs.github.com/en/pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request#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
Expand Down
1 change: 1 addition & 0 deletions news/+peer-review.documentation
Original file line number Diff line number Diff line change
@@ -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`