Skip to content
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

Update DEPs terminology to match current landscape #95

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
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
4 changes: 2 additions & 2 deletions accepted/README.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Approved DEPs
=============

DEPs that have been approved by the Technical Board and are in the
DEPs that have been approved by the Steering Council and are in the
process of being implemented. See `DEP 1 <../final/0001-dep-process.rst>`_ for
details.
details.
42 changes: 24 additions & 18 deletions draft/0007-dependency-policy.rst

Choose a reason for hiding this comment

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

I notice we have two DEP 7s:

  • final/0007-official-projects.rst
  • draft/0007-dependency-policy.rst

It's probably out of scope of this PR to fix this, but I think the draft DEP 7 should be re-numbered.

Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ policy of "no external dependencies allowed."
In a nutshell, the policy is that adding a new external dependency should be
treated similarly to adding a major new feature to Django: it requires a DEP,
demonstration that the dependency is needed, rough consensus among the
community and core team that the chosen dependency, and a final decision by
the Technical Board.
community and core contributors that the chosen dependency,
and a final decision by the Steering Council.

The rest of this document explains the guidelines and process for adding new
dependencies, as well as the background and motivation about why this policy was
Expand Down Expand Up @@ -56,7 +56,7 @@ as Django itself. We define "maturity" as:
issues that wouldn't make it into Django shouldn't be accepted as a dependency,
either.

- **Maintained** - if we discover bugs in a dependency, we need to be fairly
- **Maintained** - if we discover bugs in a dependency, we need to be fairly
confident that they'll be fixed quickly.

- **Takes security seriously** - we should be confident that if we or our users
Expand All @@ -65,18 +65,18 @@ as Django itself. We define "maturity" as:
should have a vulnerability disclosure policy, security-specific contacts,
and a history of taking vulnerabilities seriously.

- **Works on all the same platforms as Django does** - Linux, Mac, Windows,
and all supported Python versions (including PyPy). This probably means that
dependencies that require C extensions are probably not acceptable [1]_.
- **Works on all the same platforms as Django does** - Linux, Mac, Windows,
and all supported Python versions (including PyPy). This probably means that
dependencies that require C extensions are probably not acceptable [1]_.

- **Backwards compatible** in minor releases. We should be able to specify as
wide a range of required versions as possible so that releases of Django
are de-coupled (as much as possible) from dependencies. Generally, we'll
want to specify dependencies as ``foo>=1.0,<2.0``, and be confident that
point-releases of ``foo`` won't break Django.
point-releases of ``foo`` won't break Django.

Again, these are guidelines. At the end of the day, the criteria comes down to
"would we include this code in Django?" The Tech Board has the final call.
"would we include this code in Django?" The Steering Council has the final call.

.. [1] Note the "probably" there. It is, in principle, possible to distribute
C extensions in a way that no longer requires a compiler -- platform-
Expand All @@ -103,8 +103,8 @@ answers a few questions:
- What's the dependency? Why should we use it over re-inventing this
particular wheel [2]_?

- Does the package meet the maturity bar laid out above? If there are
any maturity risks -- for example, if the project only has a single
- Does the package meet the maturity bar laid out above? If there are
any maturity risks -- for example, if the project only has a single
maintainer -- that should be identified so we can do a cost/benefit
analysis.

Expand All @@ -123,11 +123,11 @@ Re-evaluating dependencies
--------------------------

During each minor release cycle -- and especially before LTS releases -- the
core team should re-evaluate all existing dependencies. If some dependency is
starting regress on the maturity front (particularly if it has become
unmaintained), we want to identify it early and start looking for backup plans.
This might mean removing the dependency, taking over maintenance ourselves,
looking for funding to pay new maintainers, etc.
core contributors should re-evaluate all existing dependencies. If some

Choose a reason for hiding this comment

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

I wonder if this should be more specific:

Suggested change
core contributors should re-evaluate all existing dependencies. If some
Steering Council and Fellows should re-evaluate all existing dependencies. If some

Otherwise, it's not really clear whose responsibility it is.

But maybe this is straying a bit far from the point of this particular PR...

dependency is starting regress on the maturity front (particularly if it has
become unmaintained), we want to identify it early and start looking for backup
plans. This might mean removing the dependency, taking over maintenance
ourselves, looking for funding to pay new maintainers, etc.

Background and Motivation
=========================
Expand All @@ -151,8 +151,8 @@ occasional downtime, leading to frustration when trying to deploy to production.
didn't go well. Many users struggled even to get the package installed.

That experience led to a deep suspicion of Python packaging tools among the
Django core team, and a de-facto policy emerged of only requiring the lowest
common denominator: installation via direct download and ``python setup.py
Django core contributors, and a de-facto policy emerged of only requiring the
lowest common denominator: installation via direct download and ``python setup.py
Comment on lines -154 to +155

Choose a reason for hiding this comment

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

Given this is a historical section I think it would be OK not to update the terminology here. That said, that's not a strong opinion.

install``. This meant not using any of Python's packaging features developed
since about 2002, including most notably dependencies. In 2016, Django's only
dependencies are optional.
Expand Down Expand Up @@ -186,7 +186,7 @@ we took full advantage of features now available.

In particular, external dependencies -- other packages specified in
``setup.py``'s ``install_requires`` argument -- should be fair game to add to
Django, when appropriate. Django core developers often duplicate effort
Django, when appropriate. Django core contributors often duplicate effort
re-implementing features that are available as dependencies. And, much of the
time, those external implementations are substantially better than what's
included in Django. For example:
Expand Down Expand Up @@ -214,6 +214,12 @@ specifically -- there may be good arguments both for and against each specific
example. They're offered here as examples to of the types of options that open
up once we start to allow external dependencies.

Revision History
================

2024-10-04
Updates to reflect current governance.

Copyright
=========

Expand Down
49 changes: 26 additions & 23 deletions final/0001-dep-process.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ DEP 1: DEP Purpose and Guidelines
:Status: Final
:Type: Process
:Created: 2014-04-14
:Last-Modified: 2023-10-21
:Last-Modified: 2023-10-21

.. contents:: Table of Contents
:depth: 3
Expand Down Expand Up @@ -105,8 +105,8 @@ or too broad. If in doubt, split your DEP into several well-focused ones.

The DEP Author (see below for the formal definition of an Author)
should first attempt to ascertain whether the idea is DEP-able. Posting to
`django-developers <https://docs.djangoproject.com/en/dev/internals/mailing-
lists /#django-developers-mailing-list>`_ is the best way to go about this.
`Django Internals on the forum <https://forum.djangoproject.com/c/internals/5>`_
is the best way to go about this.

Vetting an idea publicly before going as far as writing a DEP is meant to save
the potential author time. Many ideas have been brought forward for changing
Expand Down Expand Up @@ -144,8 +144,8 @@ Shepherd
can be someone with a long history of contributing to Django, who can help
the Author assess the fitness of their proposal and help make sure it gets
accepted. The primary job of the Shepherd will be to review the DEP in an
editorial role, and help guide the Author through the DEP process.
editorial role, and help guide the Author through the DEP process.

The Shepherd may be a `Merger`_, and if so the Shepherd will be the one who
actually merges the code into the project. Or, the Shepherd may be a
member of the Steering Council, which can help streamline discussion.
Expand All @@ -165,7 +165,7 @@ Submitting the draft
--------------------

Once the idea's been vetted and the roles are filled, a draft DEP should be
presented to the Django Forum and/or django-developers. This gives the author a
presented to the Django Forum. This gives the author a
chance to flesh out the draft DEP to make sure it's properly formatted, of high
quality, and to address initial concerns about the proposal.

Expand All @@ -177,7 +177,7 @@ until proper formatting rules are followed.

At this point, contributors will review the pull request. In most cases the reviewer
will be the Shepherd of the DEP, but if that's not possible for some reason the
author may want to ask on django-developers and/or the Django Forum to ensure
author may want to ask on the Django Forum to ensure
that this review happens quickly. A reviewer will do the following:

* Read the DEP to check if it is ready: sound and complete. The ideas
Expand All @@ -202,7 +202,7 @@ Once the DEP is ready for the repository, the reviewer will:
* Merge the pull request.

* Assign a DEP number (almost always just the next available number), and rename
the DEP file with the new number (e.g. rename ``dep-process.rst`` to
the DEP file with the new number (e.g. rename ``dep-process.rst`` to
``0001-dep-process.rst``)

Developers with commit access to the DEPs repo may create drafts directly by
Expand Down Expand Up @@ -296,17 +296,17 @@ DEP format
To save everyone time reading DEPs, they need to follow a common format
and outline; this section describes that format. In most cases, it's probably
easiest to start with copying the provided `DEP template <../template.rst>`_,
and filling it in as you go.
and filling it in as you go.

DEPs must be written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
(the same format as Django's documentation).
DEPs must be written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
(the same format as Django's documentation).

Each DEP should have the following parts:

#. A short descriptive title (e.g. "ORM expressions"), which is also reflected
in the DEP's filename (e.g. ``0181-orm-expressions.rst``).

#. A preamble -- a rST `field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_
#. A preamble -- a rST `field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_
containing metadata about the DEP, including the DEP number, the names of the
various members of the `DEP team <#forming- the-team>`_, and so forth. See
`DEP Metadata`_ below for specific details.
Expand Down Expand Up @@ -355,8 +355,8 @@ Each DEP should have the following parts:
DEP Metadata
------------

Each DEP must begin with some metadata given as an rST
`field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_.
Each DEP must begin with some metadata given as an rST
`field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_.
The headers must contain the following fields:

``DEP``
Expand Down Expand Up @@ -398,8 +398,8 @@ Auxiliary Files
---------------

DEPs may include auxiliary files such as diagrams. Such files must be named
``XXXX-descriptive-title.ext``, where "XXXX" is the DEP number,
"descriptive-title" is a short slug indicating what the file contains, and
``XXXX-descriptive-title.ext``, where "XXXX" is the DEP number,
"descriptive-title" is a short slug indicating what the file contains, and
"ext" is replaced by the actual file extension (e.g. "png").

Reporting DEP Bugs, or Submitting DEP Updates
Expand Down Expand Up @@ -435,7 +435,7 @@ a competing DEP.
If you are interested in assuming ownership of a DEP, first try to contact the
original author and ask for permission. If they approve, ask them to open a pull
request transferring the DEP to you. If the original author doesn't respond to
email within a few weeks, contact django-developers.
email within a few weeks, raise it on the Django Forum.


Differences between DEPs and PEPs
Expand All @@ -451,8 +451,8 @@ Differences between DEPs and PEPs
process either.

As stated in the preamble, the DEP process is more or less a direct copy of
the PEP process (and this document is a modified version of
`PEP 1 <https://www.python.org/dev/peps/pep-0001/>`_).
the PEP process (and this document is a modified version of
`PEP 1 <https://www.python.org/dev/peps/pep-0001/>`_).

Relative to the PEP process, we made the following changes in DEPs:

Expand All @@ -471,7 +471,7 @@ Relative to the PEP process, we made the following changes in DEPs:
index by status isn't needed.
- DEP file names are more descriptive (e.g. ``0181-orm-expressions.rst``),
again to avoid the need for additional tooling.
- DEPs are "edited" (e.g. pull request approved) by any core developer,
- DEPs are "edited" (e.g. pull request approved) by any core contributor,
rather than an explicit "editor" role like the PEP editors.

- DEPs are pronounced upon by the Steering Council, rather than a BDFL (because
Expand All @@ -481,9 +481,9 @@ Relative to the PEP process, we made the following changes in DEPs:
and Shepherd) before submission and throughout the process. With PEPs, most
are authored and implemented by the same person, but the same doesn't seem to
be true of DEPs (so far), hence the "implementer" role. As for the "shepherd":
the BDFL or BDFL-delegate tends to be much more hands-on than the Technical
Board, so the role of commenting and critiquing will be fulfilled by the
shepherd, rather than the board. Further, we've observed that features are
the BDFL or BDFL-delegate tends to be much more hands-on than the Steering
Council, so the role of commenting and critiquing will be fulfilled by the
shepherd, rather than the Council. Further, we've observed that features are
tremendously unlikely to make it into Django without a committer on board to
do the detail-work of merging a patch.

Expand All @@ -498,6 +498,9 @@ Relative to the PEP process, we made the following changes in DEPs:
Revision History
================

2024-10-04
Further updates to reflect current governance.

2023-10-23
Updates to reflect changes in governance since this document was originally
written, including changes from "Technical Board" to "Steering Council",
Expand Down
2 changes: 1 addition & 1 deletion final/0011-accessibility-team.rst
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ terminated by:
- Becoming disqualified due to actions taken by the Code of Conduct committee
of the Django Software Foundation.

- A vote of the Technical Board, or full consensus of the rest of the
- A vote of the Steering Council, or full consensus of the rest of the
Accessibility Team, if the team is considered too large, the person is not
making positive contributions, or any other sound reason.

Expand Down
2 changes: 1 addition & 1 deletion rejected/README.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Rejected DEPs
=============

DEPs that have been rejected by the Technical Board.
DEPs that have been rejected by the Steering Council.
See `DEP 1 <../final/0001-dep-process.rst>`_ for details.