PEP 676: PEP Infrastructure Process (#2173)
This commit is contained in:
Adam Turner
GitHub
parent
b6e3845f4c
commit
54e9bd01a3
|
|
@ -530,6 +530,7 @@ pep-0672.rst @encukou
|
||||||
pep-0673.rst @jellezijlstra
|
pep-0673.rst @jellezijlstra
|
||||||
pep-0674.rst @vstinner
|
pep-0674.rst @vstinner
|
||||||
pep-0675.rst @jellezijlstra
|
pep-0675.rst @jellezijlstra
|
||||||
|
pep-0676.rst @Mariatta
|
||||||
# ...
|
# ...
|
||||||
# pep-0754.txt
|
# pep-0754.txt
|
||||||
# ...
|
# ...
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,235 @@
|
||||||
|
PEP: 676
|
||||||
|
Title: PEP Infrastructure Process
|
||||||
|
Author: Adam Turner <python@quite.org.uk>
|
||||||
|
Sponsor: Mariatta <mariatta@python.org>
|
||||||
|
Discussions-To: https://discuss.python.org/t/10774
|
||||||
|
Status: Draft
|
||||||
|
Type: Process
|
||||||
|
Content-Type: text/x-rst
|
||||||
|
Created: 01-Nov-2021
|
||||||
|
Post-History: 23-Sep-2021
|
||||||
|
|
||||||
|
Abstract
|
||||||
|
========
|
||||||
|
|
||||||
|
This PEP addresses the infrastructure around rendering PEP files from
|
||||||
|
reStructuredText_ files to HTML webpages. We aim to specify a self-contained
|
||||||
|
and maintainable solution for PEP readers, authors, and editors.
|
||||||
|
|
||||||
|
Motivation
|
||||||
|
==========
|
||||||
|
|
||||||
|
As of November 2021, Python Enhancement Proposals (PEPs) are rendered in a
|
||||||
|
multi-system, multi-stage process. A continuous integration (CI) task runs a
|
||||||
|
docutils_ script to render all PEP files individually. The CI task then uploads
|
||||||
|
a tar archive to a server, where it is retrieved and rendered into the
|
||||||
|
`python.org`_ website periodically.
|
||||||
|
|
||||||
|
This places a constraint on the `python.org`_ website to handle raw HTML
|
||||||
|
uploads and handle PEP rendering, and makes the appropriate place to raise
|
||||||
|
issues unclear in some cases [1]_.
|
||||||
|
|
||||||
|
This PEP provides a specification for self-contained rendering of PEPs. This
|
||||||
|
would:
|
||||||
|
|
||||||
|
* reduce the amount of distributed configuration for supporting PEPs
|
||||||
|
* enable quality-of-life improvements for those who read, write, and review
|
||||||
|
PEPs
|
||||||
|
* solve a number of outstanding issues, and lay the path for improvements
|
||||||
|
* save volunteer maintainers' time
|
||||||
|
|
||||||
|
We propose that PEPs are accessed through peps.python.org_ at the top-level
|
||||||
|
namespace (for example `peps.python.org/pep-0008/`_), and that all custom
|
||||||
|
tooling to support rendering PEPs is hosted in the `python/peps`_ repository.
|
||||||
|
|
||||||
|
Rationale
|
||||||
|
=========
|
||||||
|
|
||||||
|
Simplifying and Centralising Infrastructure
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
As of November 2021, to locally render a PEP file, a PEP author or editor needs
|
||||||
|
to create a full local instance of the `python.org`_ website and run a number
|
||||||
|
of disparate scripts, following documentation_ that lives outside of the
|
||||||
|
`python/peps`_ repository.
|
||||||
|
|
||||||
|
The proposed implementation provides a single Makefile_ and a Python script to
|
||||||
|
render all PEP files, with options to target a web-server or local filesystem
|
||||||
|
environment.
|
||||||
|
|
||||||
|
Using a single repository to host all tooling will clarify where to raise
|
||||||
|
issues, reducing volunteer time spent in triage.
|
||||||
|
|
||||||
|
Simplified and centralised tooling may also reduce the barrier to entry to
|
||||||
|
further improvements, as the scope of the PEP rendering infrastructure is well
|
||||||
|
defined.
|
||||||
|
|
||||||
|
Quality-of-Life Improvements and Resolving Issues
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
There are several requests for additional features in reading PEPs, such as:
|
||||||
|
|
||||||
|
* syntax highlighting [2]_
|
||||||
|
* use of ``.. code-block::`` directives [2]_
|
||||||
|
* support for SVG images [3]_
|
||||||
|
* typographic quotation marks [4]_
|
||||||
|
* additional footer information [5]_
|
||||||
|
* intersphinx functionality [6]_
|
||||||
|
|
||||||
|
These are "easy wins" from this proposal, and would serve to improve the
|
||||||
|
quality-of-life for consumers of PEPs (including reviewers and writers). For
|
||||||
|
example, the reference implementation no longer requires a scheduled render
|
||||||
|
process to run, instead initiating rendering on every commit to the
|
||||||
|
`python/peps`_ repository.
|
||||||
|
|
||||||
|
Equally, there are a small number of broken items, for example list styles not
|
||||||
|
being respected or support for updating images being challenging with the
|
||||||
|
system [7]_. These would be solved by default in the proposal.
|
||||||
|
|
||||||
|
Commercial providers such as `Read the Docs`_ can additionally enhance this
|
||||||
|
experience, for example by providing rendered previews of changes in pull
|
||||||
|
requests.
|
||||||
|
|
||||||
|
Specification
|
||||||
|
=============
|
||||||
|
|
||||||
|
The proposed specification for rendering the PEP files to HTML is as per the
|
||||||
|
`reference implementation`_.
|
||||||
|
|
||||||
|
That the HTML files should be made available under peps.python.org_. The
|
||||||
|
rendered files may be hosted just as static files, and behind a content
|
||||||
|
delivery network (CDN).
|
||||||
|
|
||||||
|
The following redirect rules must be created from the `python.org`_ domain:
|
||||||
|
|
||||||
|
* /peps/ -> https://peps.python.org/
|
||||||
|
* /dev/peps/ -> https://peps.python.org/
|
||||||
|
* /peps/(.*)\.html -> https://peps.python.org/$1
|
||||||
|
* /dev/peps/(.*) -> https://peps.python.org/$1
|
||||||
|
|
||||||
|
.. code-block:: nginx
|
||||||
|
|
||||||
|
location ~ ^/dev/peps/?(.*)$ {
|
||||||
|
return 308 https://peps.python.org/$1/;
|
||||||
|
}
|
||||||
|
|
||||||
|
location ~ ^/peps/(.*)\.html$ {
|
||||||
|
return 308 https://peps.python.org/$1/;
|
||||||
|
}
|
||||||
|
|
||||||
|
location ^/(dev/)?peps(/.*)?$ {
|
||||||
|
return 308 https://peps.python.org/;
|
||||||
|
}
|
||||||
|
|
||||||
|
Redirects must be implemented to preserve `URL fragments`_ for backward
|
||||||
|
compatability purposes.
|
||||||
|
|
||||||
|
Backwards Compatibility
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Due to server-side redirects to new canonical URLs, there are no backwards
|
||||||
|
compatability concerns. Links in previously published materials referring to
|
||||||
|
any old URL scheme will be guaranteed to work.
|
||||||
|
|
||||||
|
Security Implications
|
||||||
|
=====================
|
||||||
|
|
||||||
|
No security implications, and the main `python.org`_ website will no longer
|
||||||
|
take raw HTML uploads, closing a potential threat vector.
|
||||||
|
|
||||||
|
How to Teach This
|
||||||
|
=================
|
||||||
|
|
||||||
|
The new canonical URLs will be publicised in the documentation. However, this
|
||||||
|
is mainly a backend infrastructure change, and there should be minimal
|
||||||
|
end-user impact.
|
||||||
|
|
||||||
|
Reference Implementation
|
||||||
|
========================
|
||||||
|
|
||||||
|
The proposed implementation has been merged into the `python/peps`_ repository
|
||||||
|
in a series of pull requests [8]_. This automatically renders all PEPs on every
|
||||||
|
commit.
|
||||||
|
|
||||||
|
Rejected Ideas
|
||||||
|
==============
|
||||||
|
|
||||||
|
It would likely be possible to amend the current (as of November 2021)
|
||||||
|
rendering process to include a lot of the quality-of-life improvements and
|
||||||
|
issue mitigations mentioned above. However, we do not believe that this would
|
||||||
|
solve the distributed tooling issue.
|
||||||
|
|
||||||
|
It would be possible to use the output from the proposed rendering system and
|
||||||
|
import it into `python.org`_. We would argue however that this would be the
|
||||||
|
worst of both worlds, as a great deal of complexity is added, and none is
|
||||||
|
removed.
|
||||||
|
|
||||||
|
Open Issues
|
||||||
|
===========
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
Acknowledgements
|
||||||
|
================
|
||||||
|
|
||||||
|
Thanks to Hugo van Kemenade, Pablo Galindo Salgado, and Éric Araujo for support
|
||||||
|
since April 2020.
|
||||||
|
|
||||||
|
Footnotes
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. _documentation: https://pythondotorg.readthedocs.io/pep_generation.html
|
||||||
|
.. _docutils: https://docutils.sourceforge.io
|
||||||
|
.. _Makefile: https://www.gnu.org/software/make/manual/make.html#Introduction
|
||||||
|
.. _peps.python.org: https://peps.python.org/
|
||||||
|
.. _peps.python.org/pep-0008/: https://peps.python.org/pep-0008/
|
||||||
|
.. _python.org: https://www.python.org
|
||||||
|
.. _python/peps: https://github.com/python/peps
|
||||||
|
.. _Read the Docs: https://readthedocs.org
|
||||||
|
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
|
||||||
|
.. _URL fragments: https://url.spec.whatwg.org/#concept-url-fragment
|
||||||
|
|
||||||
|
.. [1] For example,
|
||||||
|
`pythondotorg#1024 <https://github.com/python/pythondotorg/issues/1204>`__,
|
||||||
|
`pythondotorg#1038 <https://github.com/python/pythondotorg/issues/1038>`__,
|
||||||
|
`pythondotorg#1387 <https://github.com/python/pythondotorg/issues/1387>`__,
|
||||||
|
`pythondotorg#1388 <https://github.com/python/pythondotorg/issues/1388>`__,
|
||||||
|
`pythondotorg#1393 <https://github.com/python/pythondotorg/issues/1393>`__,
|
||||||
|
`pythondotorg#1564 <https://github.com/python/pythondotorg/issues/1564>`__,
|
||||||
|
`pythondotorg#1913 <https://github.com/python/pythondotorg/issues/1913>`__,
|
||||||
|
.. [2] Requested: `pythondotorg#1063 <https://github.com/python/pythondotorg/pull/1063>`__,
|
||||||
|
`pythondotorg#1206 <https://github.com/python/pythondotorg/issues/1206>`__,
|
||||||
|
`pythondotorg#1638 <https://github.com/python/pythondotorg/pull/1638>`__,
|
||||||
|
`peps#159 <https://github.com/python/peps/issues/159>`__,
|
||||||
|
`comment in peps#1571 <https://github.com/python/peps/pull/1571#discussion_r478701944>`__,
|
||||||
|
`peps#1577 <https://github.com/python/peps/pull/1577>`__,
|
||||||
|
.. [3] Requested: `peps#701 <https://github.com/python/peps/issues/701>`__
|
||||||
|
.. [4] Requested: `peps#165 <https://github.com/python/peps/issues/165>`__
|
||||||
|
.. [5] Requested: `pythondotorg#1564 <https://github.com/python/pythondotorg/issues/1564>`__
|
||||||
|
.. [6] Requested: `comment in peps#2 <https://github.com/python/peps/issues/2#issuecomment-339195595>`__
|
||||||
|
.. [7] As of November 2021, see
|
||||||
|
`peps#1387 <https://github.com/python/peps/issues/1387>`__,
|
||||||
|
`pythondotorg#824 <https://github.com/python/pythondotorg/issues/824>`__,
|
||||||
|
`pythondotorg#1556 <https://github.com/python/pythondotorg/pull/1556>`__,
|
||||||
|
.. [8] Implementation PRs:
|
||||||
|
`peps#1930 <https://github.com/python/peps/pull/1930>`__,
|
||||||
|
`peps#1931 <https://github.com/python/peps/pull/1931>`__,
|
||||||
|
`peps#1932 <https://github.com/python/peps/pull/1932>`__,
|
||||||
|
`peps#1933 <https://github.com/python/peps/pull/1933>`__,
|
||||||
|
`peps#1934 <https://github.com/python/peps/pull/1934>`__
|
||||||
|
|
||||||
|
Copyright
|
||||||
|
=========
|
||||||
|
|
||||||
|
This document is placed in the public domain or under the
|
||||||
|
CC0-1.0-Universal license, whichever is more permissive.
|
||||||
|
|
||||||
|
|
||||||
|
..
|
||||||
|
Local Variables:
|
||||||
|
mode: indented-text
|
||||||
|
indent-tabs-mode: nil
|
||||||
|
sentence-end-double-space: t
|
||||||
|
fill-column: 70
|
||||||
|
coding: utf-8
|
||||||
|
End:
|
||||||
Loading…
Reference in New Issue