-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
Changes from 30 commits
81150bb
c5b6b15
fb045c4
15d53aa
86a06db
9ffd9c8
dd70d1a
c8e5351
3252663
06ac18d
01234ce
d6f30d6
24bed4c
20ebb61
3ddc4e6
6cf0a1b
3b03178
00b0337
66cc1ae
5aa69bf
55d3f2d
5d43f5f
27ee5a9
877aa8b
dd1eadb
0c96723
0746c8c
8018631
98ae9b0
5ff4259
682d3a2
054a2f1
561d135
c023902
e87570c
0756f3c
dac7f61
a53cd0b
0f2b70c
d1e9f6c
cdb3082
9d29116
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* An RTD team member evaluates it to make sure it's outdated and unofficial, according to this policy | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* We delist this project from search results and send an email to owners of the RTD project | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* 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*. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
|
||
Unofficial projects | ||
~~~~~~~~~~~~~~~~~~~ | ||
|
||
A project is considered *unofficial* when it is not linked to or mentioned in *any* of the following places: | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* 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. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* All builds have failed for more than 6 months. | ||
|
||
|
||
Reachability | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
~~~~~~~~~~~~ | ||
|
||
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 | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* 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. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* 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. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Requesting a project be delisted | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
You can request that we delist an outdated, unmaintained documentation with our :doc:`/support`. | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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): ... | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Describe attempts of reaching the owner(s) of the documentation project: | ||
... | ||
humitos marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
|
||
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, | ||
benjaoming marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 |
Uh oh!
There was an error while loading. Please reload this page.