Skip to content

Add an initial policy for delisting unmaintained projects #9731

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 42 commits into from
Nov 24, 2022
Merged
Show file tree
Hide file tree
Changes from 30 commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
81150bb
Add an initial policy for delisting unmaintained projects
ericholscher Nov 14, 2022
c5b6b15
Move legalise to the bottom
ericholscher Nov 15, 2022
fb045c4
A bit more clarify
ericholscher Nov 15, 2022
15d53aa
Add to TOC
ericholscher Nov 15, 2022
86a06db
Apply the most immediately uncomplicated suggestions from code review
benjaoming Nov 16, 2022
9ffd9c8
Expand section on what "unmaintained" means
benjaoming Nov 16, 2022
dd70d1a
Add more cross-references for defined terms
benjaoming Nov 16, 2022
c8e5351
sembr
benjaoming Nov 16, 2022
3252663
Adding linebreaks
benjaoming Nov 16, 2022
06ac18d
Remove "candidate" and make it a bit more clear that someone needs to…
benjaoming Nov 16, 2022
01234ce
Add a template for emails
benjaoming Nov 16, 2022
d6f30d6
Move definitions to "specification" as @humitos suggested
benjaoming Nov 16, 2022
24bed4c
Move use cases to "Examples" under rationale
benjaoming Nov 16, 2022
20ebb61
Adds robots.txt boilerplate
benjaoming Nov 16, 2022
3ddc4e6
Add a step that the source project is notified by RTD core team
benjaoming Nov 16, 2022
6cf0a1b
resolve warning - include in TOC
benjaoming Nov 16, 2022
3b03178
Add a comment in robots.txt template
benjaoming Nov 16, 2022
00b0337
Update docs/user/unofficial-projects.rst
benjaoming Nov 17, 2022
66cc1ae
Adds a link in robots.txt to where the policy will presumably live
benjaoming Nov 17, 2022
5aa69bf
Apply suggestions from @agjohnson code review
benjaoming Nov 17, 2022
55d3f2d
Update docs/user/unofficial-projects.rst
benjaoming Nov 17, 2022
5d43f5f
Remove procedure to notify upstream maintainers
benjaoming Nov 21, 2022
27ee5a9
Change Specification to Definitions
benjaoming Nov 21, 2022
877aa8b
Merge branch 'outdated-docs-policy' of github.com:readthedocs/readthe…
benjaoming Nov 21, 2022
dd1eadb
Move High-level Overview to Rationale
benjaoming Nov 21, 2022
0c96723
Add a definition of source project
benjaoming Nov 21, 2022
0746c8c
Delisting with notification. Step added to take no further action if …
benjaoming Nov 21, 2022
8018631
Talk mostly of "owner" in plural, there might be several people maint…
benjaoming Nov 21, 2022
98ae9b0
Remove SOME stuff, we aren't going to seriously validate that
benjaoming Nov 21, 2022
5ff4259
Remove examples section, it doesn't fill much purpose now
benjaoming Nov 21, 2022
682d3a2
Apply suggestions from @humitos and @erichholscher
benjaoming Nov 22, 2022
054a2f1
reference Terms of Service doc
benjaoming Nov 22, 2022
561d135
Move delisting section
benjaoming Nov 22, 2022
c023902
Remove step outlining what happens if "unreachable" since nothing hap…
benjaoming Nov 22, 2022
e87570c
Remove definition of "Unreachable" since it's not in use
benjaoming Nov 22, 2022
0756f3c
Remove definition of Source Project
benjaoming Nov 22, 2022
dac7f61
Update docs/user/unofficial-projects.rst
benjaoming Nov 22, 2022
a53cd0b
Add cross-references to Project Policies
benjaoming Nov 23, 2022
0f2b70c
Apply suggestions from code review
benjaoming Nov 23, 2022
d1e9f6c
Update docs/user/abandoned-projects.rst
benjaoming Nov 23, 2022
cdb3082
Update docs/user/abandoned-projects.rst
benjaoming Nov 23, 2022
9d29116
ANY and ALL => **any** or **all**
benjaoming Nov 23, 2022
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
4 changes: 3 additions & 1 deletion docs/user/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,8 @@ of Read the Docs and the larger software documentation ecosystem.
* **Policies & Process**:
:doc:`security` |
:doc:`DMCA takedown policy <dmca/index>` |
:doc:`Policy for abandoned projects <abandoned-projects>` |
:doc:`/abandoned-projects` |
:doc:`/unofficial-projects` |
:doc:`Release notes & changelog <changelog>`


Expand Down Expand Up @@ -283,6 +284,7 @@ of Read the Docs and the larger software documentation ecosystem.
security
dmca/index
abandoned-projects
unofficial-projects
changelog

about
Expand Down
142 changes: 142 additions & 0 deletions docs/user/unofficial-projects.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
Policy for Unofficial and Unmaintained Projects
===============================================

This policy describes a process where we take actions against unmaintained_ and unofficial_ forks of project documentation.


Rationale
---------

Documentation projects may be kept online indefinitely, even though a newer version of the same project exists elsewhere.
There are many reasons this can happen,
including forks, old official docs that are unmaintained, and many other situations.

The problem with old, outdated docs is that users will find them in search results,
and get confused to the validity of them.
Projects will then get support requests from people who are using an old and incorrect documentation version.

We have this policy to allow a reporter to request the *delisting* of forks that are old and outdated.


High level overview
~~~~~~~~~~~~~~~~~~~

The process at a high level looks like:

* A reporter emails us about a project they think is outdated and unofficial
* An RTD team member evaluates it to make sure it's outdated and unofficial, according to this policy
* We delist this project from search results and send an email to owners of the RTD project
* If a project owner objects, we evaluate their evidence and make a final decision


Definitions
-----------


Source project
~~~~~~~~~~~~~~

For a given documentation project to be assessed, the *source project* comes into question. This is defined as:

* The origin project from which the documentation project's repository was forked (if forked).
* The origin project from which the documentation project was copied (if not forked but evidently copied).
* The original project which the documentation project refers as the subject of documentation.
* Any other project that is understood by the core team to be a the *source project*.


Unofficial projects
~~~~~~~~~~~~~~~~~~~

A project is considered *unofficial* when it is not linked to or mentioned in *any* of the following places:

* Websites and domains associated with the project
* The project's primary repository -- README files, repository description, or source code


Unmaintained projects
~~~~~~~~~~~~~~~~~~~~~

A project is considered *unmaintained* when ANY of the following are met:

* The configured version control repository is unreadable. This can happen if the repository is deleted, credentials are broken or the Git host is permanently unresponsive.
* The project is only serving content from releases and commits 6 months or older than its source repository.
* All builds have failed for more than 6 months.


Reachability
~~~~~~~~~~~~

In every case where contacting the user is necessary, the core team will reach out using one of the following means of contact:

* E-mail address on file in the user's profile
* E-mail address on the GitHub user account where the project is pointed

The core team will stop trying to reach the user after 3 weeks and the user will be considered *unreachable*.


Implementation
--------------


Delisting of an abandoned project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Projects that are determined to be unmaintained_ and unofficial_ will have a ``robots.txt`` file added that removes them from all search results:

.. code-block:: text

# robots.txt
User-agent: *
# This project is delisted according to the Policy for Unofficial and Unmaintanied Projects
# https://docs.readthedocs.io/en/stable/unofficial-projects.html
Disallow: /


Projects will be delisted if they meet *all* of the following criteria:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're using all here instead of ALL, like above. We should be consistent.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

Copy link
Contributor

@agjohnson agjohnson Nov 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a note, I changed this to be bold text in another section because using caps for emphasis is an a11y pattern to avoid, generally speaking. Capital letters can affect screen reader usage (some will output this as an acronym, not read it as a word) and all caps can negatively affect readers with dyslexia.

If we're looking for emphasis, we have native options in reST like bold, italic, etc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, changing


* The person who submits the report of the unmaintained_ and unofficial_ project also demonstrates failed attempts to contact the existing owners.
* The project has been determined unmaintained_ and unofficial_ by the rules described above.
* The project owners is notified by the Read the Docs team.
* The core team does not have any additional reservations.
* If the project owners are unreachable_ by the Read the Docs team, no further action is taken.
* If the any of the project owners respond, their response will be taken into account by the core team and it may be listed again if the criteria are met.

Requesting a project be delisted
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can request that we delist an outdated, unmaintained documentation with our :doc:`/support`.

Please include the following information:

.. code-block:: text

URL of unofficial and unmaintained documentation project: ...
URL of official documentation (if any): ...
URL of official source project website (if any): ...
URL of official source project repository (if any): ...

Describe attempts of reaching the owner(s) of the documentation project:
...


Thinking behind the policy
--------------------------

The main idea behind this policy is that Read the Docs serves the community.
Every user is invited to upload content under the Terms of Use,
understanding that it is at the sole risk of the user.

While Read the Docs is not a backup service, the core team of Read the Docs does their best to keep content accessible indefinitely in its published form. However, in certain edge cases,
the greater community's needs might outweigh the individual's expectation of continued publishing.


Prior art
---------

This policy is inspired by our :doc:`abandoned-projects`.
The Python Package Index (PyPI) policy for claiming abandoned packages
(`PEP-0541 <https://www.python.org/dev/peps/pep-0541>`_) heavily influenced this policy.

.. _unmaintained: #unmaintained-projects
.. _unofficial: #unofficial-projects
.. _unreachable: #reachability