Skip to content

Move peps into subdirectory #10

Closed

Description

@birkenfeld

The root directory listing is currently very long, which means that nobody will see github's readme rendering.

The peps sources could be moved into a subdirectory, separated from the scripts used to generate the rendered versions.

Activity

  1. hugovk commented on Jun 24, 2022

    @hugovk
    Member

    +1

    • the lack of git log --follow functionality on GitHub: it now exists. The loss of history navigability on the GitHub is no longer a thing.

    We could also reconsider #1 "Use .rst as the file extension for reST-based PEPs", which was also rejected due to history: #1 (comment).

  2. pradyunsg commented on Jun 24, 2022

    @pradyunsg
    Member

    Indeed, that would also include #4.

  3. CAM-Gerlach commented on Jun 24, 2022

    @CAM-Gerlach
    Member

    While it can't get us back the substantial hassle of having to finagle the includes/excludes to fix the many issues that dumping all the PEPs in the root directory and naming many of them .txt instead of .rst has caused us in the past (e.g. #2423 , #2405 , #2264 , and parts of several others), it will certainly help avoid any future issues going forward, and allow us to re-simplify the custom config and plugins/hacks we have in place to deal with this. Additionally, it adds a time and complexity cost to everyday grepping as well as finding/scrolling through all the PEP files in the root to find the few important non-PEP ones. Also, its caused a fair amount of confusion in the past, since its ambiguous whether arbitrary non-PEP files in the root are meta-documentation/build scripts/config/etc. at the repo level, or are associated with individual PEPs.

    Given that now the main reasons for not doing this (chiefly, GitHub not tracking moves) are no longer an issue (several other things surrounding this have been improved as well), I'm 👍 on this change (moving all the PEPs to a peps subdir with a consistent .rst extension, and am willing to help make it happen (we'd need to tweak the makefile and build config, update the path in the linting checks, and make sure everything still works).

    Indeed, that would also include #4.

    To note, that was already completed many years ago and all the PEPs are using reST syntax internally, just that the old PEPs still used the .txt extension (#4) for historical reasons, which are now no longer relevant as you mention.

  4. AA-Turner commented on Jun 25, 2022

    @AA-Turner
    Member

    I don't remember where, but someone made the point that for PEPs, the text files are the project, rather than in support of the project, as is the case with standard documentation.

    I'd be in favour of cleaning up the ancialliary files where possible, but I don't think we should move the files, even if we can.

    A

  5. hugovk commented on Jun 25, 2022

    @hugovk
    Member

    Even so, many projects have their main project files under a subdirectory, for example src/project_name or project_name, and tests and other stuff elsewhere.

  6. merwok commented on Jun 25, 2022

    @merwok
    Member

    for PEPs, the text files are the project, rather than in support of the project

    That line of argument sounds a bit philosophical, but the point being discussed here is purely a practical matter due to the current code host in use.

  7. CAM-Gerlach commented on Jun 28, 2022

    @CAM-Gerlach
    Member

    Even so, many projects have their main project files under a subdirectory, for example src/project_name or project_name, and tests and other stuff elsewhere.

    Indeed, that's pretty much all Python projects, many of which have the tests inline with the code in the subdir rather than under another subdirectory, along with many (most) other languages (e.g. src), and even on the various docs projects I contribute to, very often the docs are still in a docs subdir, even if the top-level repo is just docs. Same with e.g. static sites, which typically include all content in a content or similar subdir, even if there are minimal supporting files.

    That line of argument sounds a bit philosophical, but the point being discussed here is purely a practical matter due to the current code host in use.

    Indeed; practicality over purity. The reasons advanced for the move are essentially all practical in nature, namely:

    • Creates a clean, clear separation between PEP content and non-PEP files for humans and tools that doesn't require parsing filename patterns
    • Allows us to simplify the config and custom Sphinx filtering code that is currently required to deal with this and avoiding issues in the future similar to the many we've had to deal with in the past
    • Makes the readme, meta-documentation, build scripts, etc. much easier to find and navigate to, on GitHub and locally
    • Reduces the time/complexity cost to everyday grepping, globbing and searching
    • Easier to understand and less overwhelming to newer PEP authors

    Therefore, if we're going to move anything anyway (which git doesn't care if its a rename or a move), we may as well just do things properly at the same time to really get the benefit of it.

  8. Semnodime commented on Jan 13, 2023

    @Semnodime
    Contributor

    @CAM-Gerlach, I would like to help transition all PEPs from .txt to .rst, moving them into a common subdir, etc, by creating a PR, just as @timofurrer attempted in 2016 via timofurrer@b6afc70.

    • Anybody else working on this currently?
    • How can collaboration be organized for this issue?
  9. CAM-Gerlach commented on Jan 13, 2023

    @CAM-Gerlach
    Member

    The actual move (and rename of the PEPs to .rst) is fairly trivial for any of us to do; there are a handful of other things that need to be updated/simplified afterward, but realistically that's best (and most easily) done by a PEP editor familiar with all the infrastructure involved, assuming we decide to actually go ahead with it.

    However, there are a number of tasks to fix outstanding technical/editorial defects that you could help with right now with relatively that should be much more achievable, helpful to use and beneficial to PEP readers and authors, such as:

    • Fixing the remaining docutils/Sphinx warnings
    • Adding the necessary lexer tags to non-Python code blocks on old PEPs so they are syntax-highlighted correctly
    • Adding missing URLs to the discussions-to, post history and resolution headers
    • Repairing broken external links, and fixing any other clear defects

    To note, we don't generally suggest opening big PRs doing the same thing to a bunch of PEPs, especially as a newer contributor. Instead, a good approach to this is to pick one PEP that has at least one build warning, fix that and each of the other technical issues present (one type of fix per commit), and then submit that as a PR for review. See, e.g. #2751, #2754 or any of Hugo's other similar PRs for examples.

    I plan to open a meta-issue (hopefully later today; I've already written up a lot of it) documenting this approach and tracking the main remaining defect-fixing tasks that have value and meet the criteria, with a particular eye toward making it straightforward for any contributor to help with. Keep an eye out for that if you're interested in helping out. Thanks!

  10. added
    infraCore infrastructure for building and rendering PEPs
    and removed on Jan 13, 2023
  11. hugovk commented on Jan 14, 2023

    @hugovk
    Member

    Re: fixing warnings, here's the checklist I'd been working from.

    Details

    Sorted by number of warnings

    Fixed warnings

    pep-0593.rst:265: WARNING: Citation [struct-doc] is not referenced.
    pep-0593.rst:265: WARNING: duplicate citation mypy, other instance in pep-0484.txt
    pep-0593.rst:271: WARNING: duplicate citation pycharm, other instance in pep-0482.txt
    pep-0484.txt:2490: WARNING: Citation [peps] is not referenced.
    pep-0484.txt:2463: WARNING: duplicate citation mypy, other instance in pep-0482.txt
    pep-0484.txt:2475: WARNING: duplicate citation pyflakes, other instance in pep-0482.txt
    pep-0484.txt:2478: WARNING: duplicate citation pylint, other instance in pep-0482.txt
    pep-0520.txt:416: WARNING: Citation [nick_concern] is not referenced.
    pep-0520.txt:419: WARNING: Citation [orig] is not referenced.
    pep-0520.txt:422: WARNING: Citation [followup1] is not referenced.
    pep-0520.txt:425: WARNING: Citation [followup2] is not referenced.
    pep-0554.rst:1709: WARNING: Citation [nathaniel-asyncio] is not referenced.
    pep-0554.rst:1712: WARNING: Citation [extension-docs] is not referenced.
    pep-0554.rst:1645: WARNING: Citation [CSP] is not referenced.
    pep-0554.rst:1677: WARNING: Citation [mp-conn] is not referenced.
    pep-0554.rst:1686: WARNING: Citation [main-thread] is not referenced.
    pep-0553.rst:283: WARNING: Citation [envar] is not referenced.
    pep-0661.rst:323: WARNING: Footnote [5] is not referenced.
    pep-0661.rst:324: WARNING: Footnote [6] is not referenced.
    pep-0661.rst:325: WARNING: Footnote [7] is not referenced.
    pep-0661.rst:326: WARNING: Footnote [8] is not referenced.
    pep-0538.txt:1181: WARNING: Footnote [1] is not referenced.
    pep-0538.txt:1184: WARNING: Footnote [2] is not referenced.
    pep-0538.txt:1187: WARNING: Footnote [3] is not referenced.
    pep-0538.txt:1190: WARNING: Footnote [4] is not referenced.
    pep-0538.txt:1193: WARNING: Footnote [5] is not referenced.
    pep-0538.txt:1196: WARNING: Footnote [6] is not referenced.
    pep-0538.txt:1199: WARNING: Footnote [7] is not referenced.
    pep-0538.txt:1202: WARNING: Footnote [8] is not referenced.
    pep-0538.txt:1205: WARNING: Footnote [9] is not referenced.
    pep-0538.txt:1208: WARNING: Footnote [10] is not referenced.
    pep-0538.txt:1211: WARNING: Footnote [11] is not referenced.
    pep-0538.txt:1214: WARNING: Footnote [12] is not referenced.
    pep-0538.txt:1217: WARNING: Footnote [13] is not referenced.
    pep-0538.txt:1220: WARNING: Footnote [14] is not referenced.
    pep-0538.txt:1223: WARNING: Footnote [15] is not referenced.
    pep-0538.txt:1226: WARNING: Footnote [16] is not referenced.
    pep-0538.txt:1229: WARNING: Footnote [17] is not referenced.
    pep-0538.txt:1232: WARNING: Footnote [18] is not referenced.
    pep-0538.txt:1235: WARNING: Footnote [19] is not referenced.
    pep-0538.txt:1238: WARNING: Footnote [20] is not referenced.
    pep-0538.txt:1241: WARNING: Footnote [21] is not referenced.
    pep-0538.txt:1244: WARNING: Footnote [22] is not referenced.
    pep-0501.txt:557: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:560: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:563: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:566: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:568: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:570: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:572: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:574: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:577: WARNING: Footnote [#] is not referenced.
    pep-0501.txt:580: WARNING: Footnote [#] is not referenced.
    pep-0432.txt:1381: WARNING: Footnote [1] is not referenced.
    pep-0432.txt:1384: WARNING: Footnote [2] is not referenced.
    pep-0432.txt:1387: WARNING: Footnote [3] is not referenced.
    pep-0432.txt:1390: WARNING: Footnote [4] is not referenced.
    pep-0432.txt:1393: WARNING: Footnote [5] is not referenced.
    pep-0432.txt:1396: WARNING: Footnote [6] is not referenced.
    pep-0432.txt:1399: WARNING: Footnote [7] is not referenced.
    pep-0432.txt:1403: WARNING: Footnote [8] is not referenced.
    pep-0432.txt:1406: WARNING: Footnote [9] is not referenced.
    pep-0432.txt:1409: WARNING: Footnote [10] is not referenced.
    pep-0642.rst:1835: WARNING: Footnote [1] is not referenced.
    pep-0642.rst:1838: WARNING: Footnote [2] is not referenced.
    pep-0642.rst:1841: WARNING: Footnote [3] is not referenced.
    pep-0642.rst:1844: WARNING: Footnote [4] is not referenced.
    pep-0642.rst:1847: WARNING: Footnote [5] is not referenced.
    pep-0642.rst:1850: WARNING: Footnote [6] is not referenced.
    pep-0642.rst:1853: WARNING: Footnote [7] is not referenced.
    pep-0642.rst:1856: WARNING: Footnote [8] is not referenced.
    pep-0642.rst:1859: WARNING: Footnote [9] is not referenced.
    pep-0634.rst:140: WARNING: duplicate label guards, other instance in pep-0622.rst
    pep-0634.rst:175: WARNING: duplicate label patterns, other instance in pep-0622.rst
    pep-0634.rst:231: WARNING: duplicate label literal_pattern, other instance in pep-0622.rst
    pep-0634.rst:267: WARNING: duplicate label capture_pattern, other instance in pep-0622.rst
    pep-0634.rst:290: WARNING: duplicate label wildcard_pattern, other instance in pep-0622.rst
    pep-0634.rst:337: WARNING: duplicate label sequence_pattern, other instance in pep-0622.rst
    pep-0634.rst:417: WARNING: duplicate label mapping_pattern, other instance in pep-0622.rst
    pep-0634.rst:472: WARNING: duplicate label class_pattern, other instance in pep-0622.rst
    pep-0634.rst:598: WARNING: duplicate label appendix a, other instance in pep-0622.rst
    pep-0601.txt:223: WARNING: Footnote [1] is not referenced.
    pep-0601.txt:225: WARNING: Footnote [2] is not referenced.
    pep-0601.txt:227: WARNING: Footnote [3] is not referenced.
    pep-0601.txt:229: WARNING: Footnote [4] is not referenced.
    pep-0601.txt:231: WARNING: Footnote [5] is not referenced.
    pep-0601.txt:233: WARNING: Footnote [6] is not referenced.
    pep-0601.txt:235: WARNING: Footnote [7] is not referenced.
    pep-0601.txt:237: WARNING: Footnote [8] is not referenced.
    pep-0601.txt:239: WARNING: Footnote [9] is not referenced.
    pep-0565.rst:337: WARNING: Footnote [1] is not referenced.
    pep-0565.rst:340: WARNING: Footnote [2] is not referenced.
    pep-0565.rst:343: WARNING: Footnote [3] is not referenced.
    pep-0565.rst:346: WARNING: Footnote [4] is not referenced.
    pep-0565.rst:349: WARNING: Footnote [5] is not referenced.
    pep-0565.rst:352: WARNING: Footnote [6] is not referenced.
    pep-0565.rst:355: WARNING: Footnote [7] is not referenced.
    pep-0565.rst:358: WARNING: Footnote [8] is not referenced.
    pep-0565.rst:361: WARNING: Footnote [9] is not referenced.
    pep-0635.rst:403: WARNING: duplicate label patterns, other instance in pep-0634.rst
    pep-0635.rst:592: WARNING: duplicate label literal_pattern, other instance in pep-0634.rst
    pep-0635.rst:681: WARNING: duplicate label capture_pattern, other instance in pep-0634.rst
    pep-0635.rst:740: WARNING: duplicate label wildcard_pattern, other instance in pep-0634.rst
    pep-0635.rst:907: WARNING: duplicate label sequence_pattern, other instance in pep-0634.rst
    pep-0635.rst:967: WARNING: duplicate label mapping_pattern, other instance in pep-0634.rst
    pep-0635.rst:1014: WARNING: duplicate label class_pattern, other instance in pep-0634.rst
    pep-0605.rst:1346: WARNING: Footnote [1] is not referenced.
    pep-0605.rst:1349: WARNING: Footnote [2] is not referenced.
    pep-0605.rst:1352: WARNING: Footnote [3] is not referenced.
    pep-0605.rst:1355: WARNING: Footnote [4] is not referenced.
    pep-0605.rst:1358: WARNING: Footnote [5] is not referenced.
    pep-0605.rst:1361: WARNING: Footnote [6] is not referenced.
    pep-0550.rst:1704: WARNING: Footnote [4] is not referenced.
    pep-0550.rst:1718: WARNING: Footnote [11] is not referenced.
    pep-0550.rst:1720: WARNING: Footnote [13] is not referenced.
    pep-0550.rst:1722: WARNING: Footnote [14] is not referenced.
    pep-0550.rst:1724: WARNING: Footnote [15] is not referenced.
    pep-0550.rst:1726: WARNING: Footnote [16] is not referenced.
    pep-0467.txt:239: WARNING: Footnote [1] is not referenced.
    pep-0467.txt:241: WARNING: Footnote [2] is not referenced.
    pep-0467.txt:243: WARNING: Footnote [3] is not referenced.
    pep-0467.txt:245: WARNING: Footnote [4] is not referenced.
    pep-0467.txt:247: WARNING: Footnote [5] is not referenced.
    pep-0467.txt:249: WARNING: Footnote [6] is not referenced.
    pep-0558.rst:1299: WARNING: Footnote [2] is not referenced.
    pep-0558.rst:1323: WARNING: Footnote [10] is not referenced.
    pep-0558.rst:1326: WARNING: Footnote [11] is not referenced.
    pep-0558.rst:1329: WARNING: Footnote [12] is not referenced.
    pep-0558.rst:1332: WARNING: Footnote [13] is not referenced.
    pep-0532.txt:886: WARNING: Footnote [1] is not referenced.
    pep-0532.txt:889: WARNING: Footnote [2] is not referenced.
    pep-0532.txt:892: WARNING: Footnote [3] is not referenced.
    pep-0577.rst:806: WARNING: Footnote [1] is not referenced.
    pep-0577.rst:809: WARNING: Footnote [2] is not referenced.
    pep-0577.rst:812: WARNING: Footnote [3] is not referenced.
    pep-0577.rst:815: WARNING: Footnote [4] is not referenced.
    pep-0598.rst:885: WARNING: Footnote [1] is not referenced.
    pep-0598.rst:888: WARNING: Footnote [2] is not referenced.
    pep-0598.rst:891: WARNING: Footnote [3] is not referenced.
    pep-3150.txt:753: WARNING: Footnote [5] is not referenced.
    pep-3150.txt:768: WARNING: Footnote [10] is not referenced.
    pep-0531.txt:640: WARNING: Footnote [6] is not referenced.
    pep-0535.txt:182: WARNING: Footnote [1] is not referenced.
    pep-0440.txt:1559: WARNING: Footnote [1] is not referenced.
    pep-0440.txt:1565: WARNING: Footnote [3] is not referenced.
    pep-0440.txt:1583: WARNING: Footnote [9] is not referenced.
    pep-0430.txt:208: WARNING: Footnote [1] is not referenced.
    pep-0430.txt:211: WARNING: Footnote [2] is not referenced.
    pep-0430.txt:214: WARNING: Footnote [3] is not referenced.
    pep-0395.txt:727: WARNING: Footnote [4] is not referenced.
    pep-0366.txt:136: WARNING: Footnote [4] is not referenced.
    pep-0231.txt:616: WARNING: Footnote [8] is not referenced.
    pep-0003.txt:72: WARNING: Footnote [1] is not referenced.
    

    Remaining warnings

    pep-0262.txt:318: WARNING: Footnote [1] is not referenced.
    pep-0277.txt:106: WARNING: Footnote [1] is not referenced.
    pep-0292.txt:201: WARNING: Footnote [3] is not referenced.
    pep-0292.txt:206: WARNING: Footnote [5] is not referenced.
    pep-0299.txt:112: WARNING: Footnote [1] is not referenced.
    pep-0323.txt:478: WARNING: Footnote [1] is not referenced.
    pep-0323.txt:481: WARNING: Footnote [2] is not referenced.
    pep-0326.txt:448: WARNING: Footnote [5] is not referenced.
    pep-0326.txt:458: WARNING: Footnote [8] is not referenced.
    pep-0326.txt:466: WARNING: Footnote [11] is not referenced.
    pep-0329.txt:258: WARNING: Footnote [2] is not referenced.
    pep-0336.txt:122: WARNING: Footnote [1] is not referenced.
    pep-0232.txt:250: WARNING: Footnote [3] is not referenced.
    pep-0340.txt:566: WARNING: Footnote [1] is not referenced.
    pep-0343.txt:956: WARNING: Footnote [12] is not referenced.
    pep-0355.txt:549: WARNING: Footnote [1] is not referenced.
    pep-0361.txt:273: WARNING: Footnote [1] is not referenced.
    pep-0370.txt:219: WARNING: Footnote [6] is not referenced.
    pep-0371.txt:420: WARNING: Footnote [6] is not referenced.
    pep-0371.txt:427: WARNING: Footnote [8] is not referenced.
    pep-3115.txt:300: WARNING: Footnote [1] is not referenced.
    pep-3115.txt:303: WARNING: Footnote [2] is not referenced.
    pep-3115.txt:306: WARNING: Footnote [3] is not referenced.
    pep-3115.txt:309: WARNING: Footnote [4] is not referenced.
    pep-3119.txt:846: WARNING: Footnote [2] is not referenced.
    pep-3119.txt:849: WARNING: Footnote [3] is not referenced.
    pep-3119.txt:868: WARNING: Footnote [9] is not referenced.
    pep-3119.txt:871: WARNING: Footnote [10] is not referenced.
    pep-3135.txt:216: WARNING: Footnote [1] is not referenced.
    pep-3135.txt:219: WARNING: Footnote [2] is not referenced.
    pep-3100.txt:346: WARNING: Footnote [26] is not referenced.
    pep-3104.txt:485: WARNING: Footnote [15] is not referenced.
    pep-3114.txt:208: WARNING: Footnote [6] is not referenced.
    pep-3145.txt:137: WARNING: Footnote [8] is not referenced.
    pep-3147.txt:607: WARNING: Footnote [21] is not referenced.
    pep-0617.rst:798: WARNING: Footnote [#] is not referenced.
    pep-0622.rst:2223: WARNING: Footnote [1] is not referenced.
    pep-0622.rst:2235: WARNING: Footnote [5] is not referenced.
    pep-0636.rst:459: WARNING: duplicate label appendix a, other instance in pep-0634.rst
    pep-0644.rst:366: WARNING: Footnote [11] is not referenced.
    pep-0645.rst:151: WARNING: Footnote [2] is not referenced.
    pep-0645.rst:153: WARNING: Footnote [3] is not referenced.
    pep-0654.rst:1494: WARNING: Footnote [13] is not referenced.
    pep-0571.rst:361: WARNING: Footnote [18] is not referenced.
    pep-0572.rst:1317: WARNING: Footnote [1] is not referenced.
    pep-0531.txt:634: WARNING: Footnote [4] is not referenced.
    pep-0531.txt:637: WARNING: Footnote [5] is not referenced.
    pep-0545.txt:573: WARNING: Footnote [2] is not referenced.
    pep-0502.txt:688: WARNING: Footnote [10] is not referenced.
    pep-0502.txt:692: WARNING: Footnote [11] is not referenced.
    pep-0505.rst:858: WARNING: Footnote [5] is not referenced.
    pep-0480.txt:888: WARNING: Footnote [6] is not referenced.
    pep-0480.txt:891: WARNING: Footnote [9] is not referenced.
    pep-0480.txt:892: WARNING: Footnote [10] is not referenced.
    pep-0488.txt:333: WARNING: Footnote [10] is not referenced.
    pep-0491.txt:537: WARNING: Footnote [1] is not referenced.
    pep-0492.txt:1404: WARNING: Footnote [1] is not referenced.
    pep-0448.txt:232: WARNING: Footnote [3] is not referenced.
    pep-0453.txt:1024: WARNING: Footnote [1] is not referenced.
    pep-0453.txt:1027: WARNING: Footnote [2] is not referenced.
    pep-0453.txt:1030: WARNING: Footnote [3] is not referenced.
    pep-0453.txt:1033: WARNING: Footnote [4] is not referenced.
    pep-0453.txt:1036: WARNING: Footnote [5] is not referenced.
    pep-0425.txt:274: WARNING: Footnote [1] is not referenced.
    pep-0425.txt:277: WARNING: Footnote [2] is not referenced.
    pep-0426.txt:1510: WARNING: Footnote [1] is not referenced.
    pep-0400.txt:213: WARNING: duplicate label appendix a, other instance in pep-0642.rst
    pep-0413.txt:916: WARNING: Footnote [2] is not referenced.
    pep-0419.txt:511: WARNING: Footnote [4] is not referenced.
    pep-0419.txt:514: WARNING: Footnote [5] is not referenced.
    
  12. CAM-Gerlach commented on Jan 14, 2023

    @CAM-Gerlach
    Member

    Wow, didn't know you were tracking that in such detail. That would be really good to include in the meta tracking issue I'm about to create covering that, I was just going to include a clean-up dump of the warnings I had)

  13. hugovk commented on Jan 14, 2023

    @hugovk
    Member

    The numbers may be a little off by the shifting sands of fixing other warnings (e.g. a duplicate fixed in one fixes the other), but gives a good enough idea.

  14. rafsaf commented on Apr 2, 2023

    @rafsaf

    @CAM-Gerlach
    You mentioned repairing broken external links.

    The job can be started by looking for any links around and assume that anything with 404 response code is broken.

    For example https://bitbucket.org/larsyencken/simplestats/src/c42e048a6625/src/basic.py in https://peps.python.org/pep-0450/

    If you have will and time, this would be extra helpful to hint us what is expected fix for this, where like above, the repository on bitbucket mentioned in PEP probably was removed. Web archive? Marking somehow links as not alive? Tried to find answers in https://peps.python.org/pep-0001/#pep-maintenance

  15. CAM-Gerlach commented on Apr 2, 2023

    @CAM-Gerlach
    Member

    You mentioned repairing broken external links.

    it's one of the lower-priority list items given the immense number of links (many thousands) among the various PEPs, and the average age of many of them (considering the PEPs span two decades). In general, I'd only recommend doing so on PEP if you're already in the process of updating it to fix the higher-priority items in the list (warnings, wrong syntax highlighting, missing headers, substantial rendering/technical defects), and focusing on the PEPs that have the highest-priority defects and those that are Draft, Accepted and Active (for Process/Informational) or Final (for Standards Track) first over those that are Deferred, Withdrawn, Rejected or Superseded.

    The job can be started by looking for any links around and assume that anything with 404 response code is broken.

    You'd do this with sphinx linkcheck (or make linkcheck, which calls it), and looking for the errors (highlighted in red)

    If you have will and time, this would be extra helpful to hint us what is expected fix for this

    You'll want to use good case-by-case judgement, but in general, the fallback order I'd suggest is:

    1. Try to find where the original page, or its current equivalent has been relocated to.
    2. Use an archive.org Wayback Machine snapshot as close as possible to the date the page was originally linked (per the PEP's Git history)
    3. If all attempts to resolve the link fail, add it to the linkcheck_ignore list in conf.py

    In this case, I just googled larsyencken simplestats and the first hit was the GitHub repo corresponding to that project. I can't be 100% sure which exact commit was linked, the hash in the URL presumably corresponds to a Mercurial changeset rather than a Git commit, but given per the URL it was before the package directory was changed from src to simplestats, and there was only one change to the file since the initial version prior to the src change, which was on the same day as the other change, the link should thus be updated to point to https://github.com/larsyencken/simplestats/blob/2be84e46814786b0cf2e88671bdb02aa7d39ef6b/src/basic.py

    Tried to find answers in https://peps.python.org/pep-0001/#pep-maintenance

    This is much too technical and low-level for PEP 1, but I do have a draft of the meta-issue mentioned above that documents the outstanding defects considered significant enough to motivate fixes to existing PEPs, the overall strategy to address them to minimize noise, churn and notifications to authors while maximizing practical, holistic benefit, and the details of how to fix each one, but haven't quite finished it quite yet—I hope to do so very soon.

  16. AA-Turner commented on Sep 9, 2023

    @AA-Turner
    Member

    This marks the closure of the final 'early' issue in the PEPs repo -- thanks to everyone for helping here!

    A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    infraCore infrastructure for building and rendering PEPs

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions