Updating our DEP process / DEP 1

Django Internals
1

We’re not really using the DEP process very much. In fact, I’ve talked to quite a few contributors who have been actively avoiding it. This I think is leading to us being somewhat “shy” about bigger changes to Django, and also leading to situations where things that really shuold have been a DEP just sorta go in without much process. So far this hasn’t bitten us, but it will.

In cleaning up DEP 1, I read back over it top to bottom, for really the first time since we wrote it in 2014. A decade on, I think there are some changes we could make to streamline things, and hopefully make the process easier to engage with.

Eventually I’ll write an “Update DEP 1” DEP, and get into the weeds, but ahead of that I’d like to have a more broad-ranging brainstorm thread where we talk about what we could change.

I’ll go first; here are the changes that are on my mind:

  • Streamline the “getting to a draft DEP” process – see django/deps#28. Basically, we should just allow a draft DEP to be created as a PR as Step 1, without requiring the pre-DEP steps.
  • Document a DEP update process. Right now there’s no explicit process for updating DEPs. I think we should clarify that we can update DEPs with a PR rather than a whole new DEP (with a vote/discussion as needed see below)
  • Allow Markdown as a DEP format
  • Explicitly move discussion on DEPs to this forum (@carltongibson informs a previous SC made this call but it’s niot written down…)
  • Clarify the decision-making process. We used to discuss major feature changes among the core team, but that team no longer exists! This means there’s an unclear step between “write DEP” and “SC votes”. I’d like to see more of a role for community discussion explicitly outlined. There are a few ways this could go, ranging from a discussion period to even formal community votes, etc. I suspect this’ll be one of the harder things to hash out but it feels worth it.

That’s my list; what would others like to see out of an updated DEP process?

6 Likes
2

That discussion (with +1s from Steering Council members) is here:

https://groups.google.com/g/django-developers/c/1NprrP2w-50/m/rpxQD2HZCAAJ

It probably doesn’t count as a formal vote, so we may as well review again anyhow. :sweat_smile:

1 Like
3

I have never seen one be proposed or implemented. So bare in mind some of this might be my lack of context. Agree with your points and…

Improve documentation to point to DEPs.
Specifically:

Note: I think the only place I can find pointing to DEPs in the Django documentation (via the search) is here Organization of the Django Project | Django documentation | Django and they are just referred to. I found out about DEPs by chance browsing Django’s repositories.

Communication on active DEPs (or feature discussions)

  • Overview - a lot of the feature discussions are either “Django Internals” section of the forum or on the django developers mailing list. I would love to be able to see “status” (concluded or not, needing more input) and all of the “new featurey” discussions of Django in one place (an overview/or can filter for them). The forum has had a lot of these discussions, I still think we can still improve the categorization of “new feature proposals” and would be interested if “status” can be implemented.
  • Advertising/announcements - I can put something in Django News but the overview would really help or having that each DEP proposed also has a post in “Announcements” or something. I think we should be quite structured in the promotion of these discussions so it doesn’t all land on the proposers.

Then I just want to reiterate this point. Feature discussions I have witnessed seem exhausting. You need to promote it and try to encourage input and then somehow manage to get a consensus and both are really hard. Improving this would be huge.

cc @Lily-Foote @thibaudcolas @nessita

5 Likes
4

Thank you @sarahboyce, super helpful!

Feature discussions I have witnessed seem exhausting.

Can you expand on this just a little bit? (Or anyone else who read that and said “yeah it is”). I mostly haven’t experienced feature conversations around here as exhausting but my role in this community is pretty different and I’m likely to experience conversations pretty differently. I’d love to understand more about what seems difficult and see if there are ways to improve that.

Thanks again!

5

This might not be very concrete as it’s an “impression” but I will try.

This one is probably my best example: Changing QuerySet.repr to avoid unexpected queries - Django Internals / ORM - Django Forum (djangoproject.com).

  • It’s the feeling that you need to convince everyone to be on board with the proposal.
  • It’s difficult to define if you have had enough input or not (let’s say three people say yes early on - is that a go?)
  • As the proposer, it is all on you to summarise, advocate, advertise, mediate.
  • It is very difficult to get the “closure” of the yes or the no.
  • Some people have more weight in the technical decisions than others. If you’re proposing something for feature X, really you need input from some of the people who are very familiar with feature X. We don’t have a way to learn who that is - the default is the fellows. I don’t know who is missing from the discussion and there’s no recognision if person A’s opinion has more weight here than person B.
6 Likes
6

This is a very good summary of my experience with proposing to change QuerySet.__repr__. I’m not a stranger to contributing to Django, but this was a much more exhausting and demotivating experience than my other contributions. If I didn’t already have a long list of successful contributions, I could imagine this putting me off attempting to contribute in the future.

In this case, I ended up feeling like I had nothing left to say and once I stopped commenting, the thread was forgotten for 4 months until another Django user added their experience.

Maybe this is a case where a DEP would have been appropriate, but it wasn’t (and still isn’t) clear to me that I should take that path.

I think the biggest problem with discussions on the forum is the lack of a clear ending point and closure for the proposal. Even in cases where there seems to be high agreement that we should make a change, it’s easy for a discussion to end up bike-shedding between two different approaches that would both be a big improvement over the status-quo. @thibaudcolas’s raising of changes to the startproject template was an excellent example of this: Discord

7 Likes
7

This. (However, I don’t think this situation only applies to the forum.)

There may be a value to identifying something (“process”, “procedure”, whatever you want to call it) akin to a “Call for a vote”.

4 Likes
8

I absolutely agree with Sarah, Lily and Ken. Other examples of feature request threads are:

Relatedly, this Discord thread on #contributor-discussion (specifically about consensus), felt somehow discouraging, as if things would intentionally be hand-wavy and slow:

[…] this thread started because people here thought the consensus approach as it plays out currently is often:

  • Prone to stalling
  • Drawn out over months or years for no other reason than the process being poor
  • Very arbitrary

[…] those three points are by design.

As a fellow, when I have to close a feature-request-as-a-ticket as wontfix, redirecting the reporter to the forum (as I understand this is the procedure), I feel uneasy because the request seems doomed from the start due to the inherent ambiguity and lack of clarity in the “getting consensus” process.

I would love if we could establish clear steps, rules, and procedures for proposing, reviewing, and deciding on features. Even better if this happen in a “reasonable” time frame.

Concretely, I think we need:

  1. A way to “list” all the feature request proposals needing a resolution. This could be its own category in the forum, or perhaps a new “Triage Stage” in a ticket (shall bringing back “design decision needed” be reconsidered?)
  2. A non ambiguous way to define when consensus was reached (for both “yes, let’s do it” and for “no, let’s not pursue that at this time”)
  3. An explicit threshold (time based? amount of participants based?) to conclude if the proposal is accepted or not
6 Likes
9

As a long-time contributor I also think contributing to Django got harder. Don’t get me wrong, this is not necessarily wrong. Django is kinda “done”, which puts a high bar on anything new. Pair that with a decision making process that favors the status quo (like we currently have) and you end up in a situation where it is exhausting to add anything and the “convincing” takes a lot of time and effort.

And I am saying this as an “old-timer”, who knows whom to ask to get a feature in. So yes, I think we need to change the process to document clearly what consensus looks like, when the steering council is supposed to be invoked etc…

I am kinda in favor of an explicit threshold like @nessita suggested. It should certainly be time based in the sense that a minimum time is required for something to be decided (especially for larger things) and should at least have a certain amount of participants (if none participates it maybe is simply not interesting enough to add?). We should also be careful about how we define participation in that context, I don’t think we would see a large outbreak of socket-puppets to sway votes, but it should still be something that is kept in mind.

3 Likes
10

I don’t have anything concrete yet, but wanted to pop in real quick and say that I’m listening and digesting, and to thank everyone for sharing their experience.

1 Like
11

On and off, I’ve been thinking about this all day. (I had a couple of discussions on the Discord about it recently, so I guess it’s been a couple of weeks really.)

Over the years I’ve been stymied by the consensus problem a number of times. I’ve experienced, hear and feel the frustration that folks express.

Nonetheless, I’ve come to appreciate and value the automatic breaking mechanism that the conversation format seems to lead to. Changes in Django are essentially impossible to roll-back, and the measure as many times as it takes approach (I would argue) has historically served Django well.

I think that’s true even though there are times when What I wanted™, including things mentioned here, didn’t make or haven’t made it in (yet).

I come back to the fact that almost every proposal goes in without any disagreement, or any dissenting voices. We focus on the small number of disagreements, because the consume our energy, but they’re remarkably rare. The strength of Django — the strength of the process — it that it makes us keep digging until we work out, how come we don’t agree in this case?

My concern is that we document a different What to do in cases of disagreement process, and then that’s employed (by historical standards) much earlier than it would have otherwise been, and we end up with solutions that in hindsight are rushed.

Our user base trusts us not to introduce unnecessary churn. (I’ve argued many times it’s kind of Django’s USP.)

So that’s the concern.

As a positive point, I think the “Do it outside core” answer is almost always available.
I think a mechanism to force a resolution should require a third party implementation first — even if that’s Look I have to monkey patch this — so we can see what’s entailed, and get feedback from a wider audience. (Project templates are a perfect case for this. Monkey patching QuerySet, less nice absolutely, but if such proved popular it would be a good indicator than changing behaviour is in fact wanted…)

A concrete case of my own is adding JSON parsing to the request, that I’ve been slowly trying to guide forward. (TODO: Links) It’s bounced around for a long time (like 10 years basically) not making progress, but that required thinking it through, and the proposed route we have is a good one, I believe, and the end result will be better for it. In the intervening time, it really wasn’t a big deal to work around, using e.g. DRF.

Summary: I don’t recall anyone ever disagreeing just for the sake of it. They just have a use case coming from a different point of view. Given how rarely that happens, we do well to pay attention when it does.

Anyhow, off my chest now. :gift:

2 Likes
12

I’m ruminating on “consensus” this morning.

Until pretty recently I’ve had a fairly naive understanding of that term. I thought it meant “everyone agrees”, or something like it. Some of the early problems we had growing the Django contributor base came down to this misunderstanding – e.g. adding new core members required full “consensus” of existing members, which at the time meant everyone effectively had a pocket veto because silence was taken as dissent.

As I’ve gotten a lot more involved in volunteer communities, I’ve developed a more nuanced understanding of what “consensus” really means in practice. It’s not a requirement for full agreement; consensus as practiced in bigger communities refers to a process for decision-making where the group commits to finding solutions that everyone (or nearly everyone) can at least live with.

Critically, consensus-based decision-making doesn’t always require literal full agreement, and doesn’t require that sort of “silence equals dissent” view that I held early on. There are versions of consensus-based decision-making that require active involvement from everyone, but also versious that don’t require that. There are versions that allow people to “stand aside” (express misgivings and be sure they’re heard, but not actually veto a decision), and even versions that allow for things to go forward despite objections. In other words, healthy consensus-based communities actually really resemble the “rough consensus and working code” model that underpins a lot of open source projects.

If you wanna get in the weeds, I like this article on consensus processes. In particular the discussions about options for resolving disagreement, and consensus decisions in large groups, feel pretty applicable to us.

Anyway, I think there’s a way of applying some of these principles to the way we make decisions, and directly codifying them into DEP 1. I do think there’s some tension here between finding a process that drives forward and doesn’t “stall”, while still being careful and measured and not introducing breaking changes. But that tension feels resolvable: we should be able to get to a decision quickly, even if that decision often tends towards “no”. I feel like a clear, quick “no” (or “not yet”) is a whole lot better than a long drawn-out “maybe” :slight_smile:

3 Likes
13

Hi Carlton & Jacob,

first off, let me say that I think that while I somewhat disagree it is probably mostly a matter of taste and not a disagreement on a technical level.

I kinda agree here, we do not and should not take changes lightly.

That is a very good point and something we should keep in mind. We are not talking about the vast majority here and I think even bigger changes can go in relatively easily, but there are some areas where we know in advance that any suggested change will hurt. What hurts me a little bit though is that we have some changes which do not break our stability guarantees or something (like adding urls.py to the startapp template) but are doomed to end up with the status quo. Do not get me wrong, there are arguments to be had for both sides, but when it doesn’t hurt the framework stability per se I am tempted to allow changes to be more beginner friendly and teach good practices. I fully realize that in some cases we will have to argue why we added X but are not going to add X² (or Y?!) but we are doing that for everything anyways already and quite often our argument is “Just because we added X in the past we are not going to repeat our mistake” – so we still have an escape hatch :wink:

Fair point, I guess we would have to analyze the existing disagreements to see whether a different set of rules would have produced a different outcome. But since we do not know if the different outcome would have been better it is pretty much worthless to do the analysis :frowning:

I for one would argue that aside from bike shedding about naming stuff we could have added it two or three releases ago already and it wouldn’t have been worse? But I might have missed the discussion on it during those last releases.

I thought that was a given and if that impression ever occurred I am sorry.

Is that something you have developed on your own or is that something that is written down for the communities in question? I am asking because I feel like that people in the Django community might have very different views of what consensus actually means for us. Count me in on that…

I agree for a definition of quickly that is not as quickly as some people might think :wink: Having an agreement on a “no” (even if it is by default) feels less of a waste of energy than an endless stream of back and forth. It would hold up on our stability guarantees and as long as it does not forbid new suggestions about the same topic there is a way to present it again.

Plenty to think about…

Cheers,
Florian

2 Likes
14

I agree with this so much!

2 Likes
15

That wasn’t my intention at all! :heart:

I was just aware I’d written quite a lot and wanted a tl;dr for folks scanning it.

The point was that when folks disagree (and we label their points “bike-shedding” &co) we essentially other them (sometimes getting cross even) and reaching the better conclusion becomes effectively impossible. Remembering (even though it’s meant to be assumed) that they’re arguing in good faith aides the exercise in empathy. (Or something :stuck_out_tongue_winking_eye:)

(I’m not giving a concrete example to stop this going off track :sweat_smile:)

The thing I absolutely agree with in this thread is making the Getting to a Draft DEP stage easier, and less intimidating. Writing a DEP is a clarifying process, that helps draw out the issues — What’s the goal: Make life easier for beginners; Is this the best way to do that? — That’s great! It shouldn’t be something that people avoid at all costs.

(Slightly joking: My historical take has kind of been that if the grass on the mailing list wasn’t long enough, “Write a DEP” was always available to make it longer. We should change that. :100:)

:bouquet:

2 Likes
16

I finally found the PSF article where it mentions burnout is often connected to conflict, regardless of the outcome. Here is states Guido felt burnout after PEP 572 (walruss operator) and led to him stepping down as BDFL.

Feel this adds a bit more context to my “exhausting” comment and that this is felt by other communities (with a similar model).

I agree reaching a no, not yet, yes in a reasonable/set timeframe would be a big improvement.

Then want to add that all feature discussions I’ve seen are polite, respectful and with good intentions. :heart:

2 Likes
17

I have enjoyed reading this topic and am glad that the discussion is being had.

From a more practical point of view, it would seem worthwhile that a couple of things could be done here on the forum or in trac as per the post from @nessita .

  1. Adding a section for feature proposals
  2. Here in the forum add a special status field within that section, that would mark the “yes”, “no”, “not yet”, “requires DEP” etc
  3. Possibly enable the voting plugin in the forum for an easy “+1”, when there are enough votes then a status should be agreed upon.

Personally, I would think the forum is a better place for the discussion on proposals as it’s more accessible to more people.

5 Likes
18

:wave: thanks for the cc @sarahboyce @Lily-Foote. Lots of people have made great points about DEPs and decision-making generally. On DEPs, personally I’d recommend to make it as easy as possible to submit a DEP (Markdown, all fields optional, start a DEP with no forum thread). If there are too many DEPs, that’s a good problem to have, but really shouldn’t be a concern in the current state.

Beyond decision-making – I’d really like to see a wider effort to improve the whole contributor experience in Django, and in particular be more respectful of people’s time. In my experience, DEPs are just the tip of the iceberg, and there are a lot other ways by which contributing to Django could be made easier / faster / more pleasant. A lot of paper cuts that contributors face. And big blockers to possible bigger changes.

I don’t think this has to be super complex or fully comprehensive to be worthwhile – just start by asking sprint participants, Djangonaut Space people, the community at large – what are your common pain points in contributing and what improvements would you suggest. With more seasoned contributors then making efforts (a DEP, perhaps! :wink:) to take on this feedback and see the changes through.

4 Likes
19

Thank you everyone for this discussion and I think many great ideas are in this thread.

I really like that the accessibility team are publishing their meeting minutes. We could have that the Steering Council has a similar process and they can discuss and conclude some of the discussions that are dragging out.

Another suggestion around gaining community consensus, we can add votes to the annual developer survey. Maybe a maximum of 2 or 3 topics can be voted on. We would need to agree a threshold for what is a Yes (maybe less than 10% are against, more for than against). If we want to get the opinion of thousands of Django developers at once, this is an option. Note that I am working at JetBrains and can coordinate the survey effort if this is a good idea.

1 Like
20

On DEPs specifically – I’ve created Feature request: allow writing a DEP in Markdown as well as rST #85 to solve a very specific pain point. Feedback very welcome!

1 Like