Page MenuHomePhabricator

RFC: Re-establish the development policies
Closed, ResolvedPublic

Description

Problem statement

We'd like to solve the following perceived problems:

  1. It is difficult for contributors and project maintainers to find policies that are relevant and must be followed.

For project maintainers, I believe we currently only expect https://www.mediawiki.org/wiki/Gerrit/%2B2 to be understood and followed. Contributors likely won't read this, instead relying on reviewers to correct them as needed.

Our other policies (deprecation, security, ..) tend to be referenced in code-review by maintainers as-needed, but not otherwise discoverable by contributors, and even maintainers themselves might not be aware of them.

It is also somewhat unclear which policies apply to all Wikimedia sofware, MediaWiki core + WMF extensions, and only MediaWiki core.

  1. It is difficult to distinguish between a documented practice and an officially adopted development policy.

An official policy may set hard requirements that are socially unacceptable to not follow, of which violations are generally expected to be reverted without prior discussion, and may eventually result in revocation. An official policy can also be expected to be up-to-date (Yeah...., more about that later!).

On the other hand, a documented best-practice might only partially represent status quo, or only apply to a narrow subset of code areas (e.g. areas maintained by the authors of the document). Such best-practices may also be amended organically by peers based on goodwill and perceived consensus. Typically, these documents are changed at will, and only reverted/discussed when someone is uncertain or disagrees; these changes usually don't require TechCom involvement.

Objective

  • It is easy to discover all our official development policies (for new contributors, and for projects maintainers).
  • Contributors are able to easily recognise a policy as one.
  • Contributors can know, as part of their discovery path, which policies are applicable to them.
  • Explicitly code into the policy that changes to the policy follow the RFC process.

Proposal

Change https://www.mediawiki.org/wiki/Development_policy to be a good entry point for our development policies. Basically, reduce it to just the following two normative statement:

  • Changes to MediaWiki core that deprecate or remove aspects of the PHP API, must follow the Deprecation policy.
  • Those with merge rights to MediaWiki core or a Wikimedia-deployed extensions/skin for MediaWiki, must follow the +2 policy for all changes they merge.

I also propose we prepend the RFC 2119 blurb, and explicitly state that normative changes must follow the RFC process.

In addition to changing the "Development policy" page, I would also propose that we move "Deprecation policy" to "Development policy/Deprecation" to clearly mark in URL and first heading that it is part of this hierarchy .

For later

If this RFC establishes the development policy as our entry point, I would recommend that afterward, we revisit some of our other documents. Then, for those we wish to keep in some form, start an RFC with the objective to revise the page in question (if needed) and incorporate it with a sentence in the development policy.

Some of the other documents that come to mind:

Event Timeline

Krinkle created this task.Mar 22 2018, 1:58 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 22 2018, 1:58 AM
Krinkle updated the task description. (Show Details)Apr 9 2018, 8:38 PM
Krinkle claimed this task.May 2 2018, 8:40 PM
kchapman edited projects, added TechCom-RFC; removed TechCom.May 3 2018, 10:59 PM
kchapman edited projects, added TechCom; removed TechCom-RFC.
Rxy added a subscriber: Rxy.May 5 2018, 4:02 AM
Tgr added a subscriber: Tgr.May 8 2018, 10:46 AM
Krinkle moved this task from Inbox to Backlog on the TechCom board.May 19 2018, 3:39 PM
Joe added a subscriber: Joe.May 19 2018, 3:42 PM

I will add to this list any other development policy I find on wikitech (and check them) as it could be interesting to have a single entry-point for our development policies.

mobrovac updated the task description. (Show Details)May 19 2018, 4:07 PM
Krinkle removed Krinkle as the assignee of this task.Sep 26 2018, 11:41 PM
Krinkle claimed this task.Dec 10 2018, 6:30 PM
Krinkle added a project: TechCom-RFC.
Krinkle updated the task description. (Show Details)
Krinkle renamed this task from TechCom: Review development policies to RFC: Re-establish the development policies.Dec 10 2018, 6:33 PM
Krinkle triaged this task as Medium priority.
Krinkle updated the task description. (Show Details)
Krinkle updated the task description. (Show Details)

A few general comments:

  • I don't think putting policies under a specific parent page (the propose Development policy/Deprecation) helps. We already have {{policy}} to denote official policies, and that should be enough.
  • Regularly reviewing policies to ensure they still reflect reality is a good thing, but just because it hasn't been updated in a while shouldn't be seen as problematic. E.g. the +2 page is listed as last being majorly updated in 2013, but IMO all of the content is still applicable and relevant. Good policies (ideally) don't require constant review and redrafting/updating.
  • There's been a recent trend I've seen in free software projects where before you submit a patch you're expected to read a giant contributing guide, and I'm not sure it's a direction we should go down. In most cases, someone submitting a patch with a non-ideal commit message or some whitespace error is more valuable than the amount of time we as maintainers would spend fixing those minor things. The parts in this task about building a good entry point for our development policies I'm totally in favor of, but I don't think we should have an expectation that everyone will read all of the policies fully before submitting patches.
  • More tangentially, I would be interested in a survey about what policies people think we're missing (or overly strict on).
mobrovac moved this task from Backlog to In progress on the TechCom board.Dec 12 2018, 12:34 PM
mobrovac moved this task from P1: Define to Under discussion on the TechCom-RFC board.
Tgr added a comment.Dec 14 2018, 6:55 PM

There's been a recent trend I've seen in free software projects where before you submit a patch you're expected to read a giant contributing guide, and I'm not sure it's a direction we should go down.

I thought the expectation is that people with +2 are familiar with the policies and can point out problems to patch authors as needed.

Krinkle added a comment.EditedFeb 6 2019, 10:16 PM

A few general comments:

  • I don't think putting policies under a specific parent page (the propose Development policy/Deprecation) helps. We already have {{policy}} to denote official policies, and that should be enough.

I think the ability to easily navigate to the entry point from an individual policy is useful. As well as the ability to clearly recognise a policy by URL. I can take it out of the RFC text, but I think this aspect is minor enough that I think this is something TechCom can own as part of managing the policy pages without it needing to be an RFC-driven decision.

  • Regularly reviewing policies to ensure they still reflect reality is a good thing, but just because it hasn't been updated in a while shouldn't be seen as problematic. E.g. the +2 page is listed as last being majorly updated in 2013, but IMO all of the content is still applicable and relevant. Good policies (ideally) don't require constant review and redrafting/updating.

Agreed.

  • There's been a recent trend I've seen in free software projects where before you submit a patch you're expected to read a giant contributing guide, and I'm not sure it's a direction we should go down. In most cases, someone submitting a patch with a non-ideal commit message or some whitespace error is more valuable than the amount of time we as maintainers would spend fixing those minor things.

Agreed. I have not (intentionally) proposed any change to what is mandatory or expected from contributors. However, I do believe that as a maintainer (with merge rights), as well as a more experienced contributor, it should be easy to find and navigate through the policies. That's why I'm proposing to adopt "Development policy" as the single entry point. New policies can then either be described in a section (if they're small) or as a separate page with only a short statement in the main policy page for the purpose of discoverability and (technically) to make it authoritative.

  • More tangentially, I would be interested in a survey about what policies people think we're missing (or overly strict on).

Agreed. After we have a minimal entry point, I plan to do some outreach for exactly this reason, as well as to re-approve any existing policies as part of it, to see how people feel about them, whether they're still followed, and whether they're still up-to-date.

Tgr added a comment.Feb 6 2019, 11:01 PM

I don't think subpages are much use as a navigation mechanism - content wikis (which have more policies and rely on them much more heavily) almost never use them. A navigation template is the standard way of exposing a (relatively) fixed sequence of pages to the user. (That said, it's a bit of a bikeshed - TechCom should certainly feel empowered to rearrange those pages without a process for establishing consensus.)

Krinkle updated the task description. (Show Details)Feb 6 2019, 11:13 PM

I've published an initial draft policy, reflecting the proposal as-is, at https://www.mediawiki.org/wiki/Development_policy/Draft_2019.

greg added a subscriber: greg.Feb 12 2019, 7:15 PM

TechCom is placing this on On Last Call ending 20 February 1pm PST(21:00 UTC, 22:00 CET)

Anomie added a subscriber: Anomie.Feb 19 2019, 5:14 PM

Change https://www.mediawiki.org/wiki/Development_policy to be a good entry point for our development policies. Basically, reduce it to just the following two normative statement

An entry point is good. There's a lot of other information currently existing on that page, though, that should probably be copied somewhere before it gets removed.

On the other hand, a documented best-practice might only partially represent status quo, or only apply to a narrow subset of code areas (e.g. areas maintained by the authors of the document). Such best-practices may also be amended organically by peers based on goodwill and perceived consensus. Typically, these documents are changed at will, and only reverted/discussed when someone is uncertain or disagrees; these changes usually don't require TechCom involvement.

It'd still be nice for them to be referenced from the entry point, IMO.

Also https://www.mediawiki.org/wiki/Manual:Coding_conventions could be added to the list of these.

Change https://www.mediawiki.org/wiki/Development_policy to be a good entry point for our development policies. Basically, reduce it to just the following two normative statement

An entry point is good. There's a lot of other information currently existing on that page, though, that should probably be copied somewhere before it gets removed.

Yeah, Iets preserve the history and current content via a subpage given it's basically a fresh start.

The idea is to propose and reintroduce these bits as needed, as well as to better distinguish between policies, guidelines, documentation, and tutorials. These are four quite different things, and I couldn't find anything besides the two statements in the draft that were obviously 1) a policy, 2) approved by the technical community and 3) obviously current and up-to-date.

There's a few tasks on-going already for adding bits of policy, such as T215465, and perhaps T208524, and T216308. These RFCs could (if this task is approved) be updated to also include a proposed amendment to the policy. Either as a section of text, or (like the two examples in current draft) on separate pages merely linked.

For anything you'd like to initiate and/or feel is most important, feel free to create RFC tasks for any particular sections on the old page and/or for other policy pages you'd like to incorporate. I'll keep going through them gradually and initiate ones myself as well.

On the other hand, a documented best-practice might only partially represent status quo, or only apply to a narrow subset of code areas (e.g. areas maintained by the authors of the document). Such best-practices may also be amended organically by peers based on goodwill and perceived consensus. Typically, these documents are changed at will, and only reverted/discussed when someone is uncertain or disagrees; these changes usually don't require TechCom involvement.

It'd still be nice for them to be referenced from the entry point, IMO.

Also https://www.mediawiki.org/wiki/Manual:Coding_conventions could be added to the list of these.

Yeah, I think we could have a navigation template on the side that lists the policies for quick access and inter-page browsing. The template could also point to an entry point (or category) for guidelines, such as these. Would that work?

Works for me.

Krinkle moved this task from Untriaged to In progress on the TechCom-RFC (TechCom-RFC-Closed) board.
Krinkle edited projects, added Performance-Team; removed Performance-Team (Radar).
Krinkle moved this task from Inbox to Doing on the Performance-Team board.
Krinkle closed this task as Resolved.Feb 26 2019, 10:18 PM
mark added a project: DBA.Apr 1 2019, 1:08 PM
mark added a subscriber: mark.

There has been some concern from our DBAs the archiving of the old policy will make it even harder for developers to find out about what database-related requirements their code should fulfill, and what the processes would be to get any schema or query changes deployed (such as a link to the Schema_changes page). The old information on database related requirements, while admittedly a bit outdated, was discussed as an RFC at the time: https://www.mediawiki.org/wiki/Architecture_meetings/RFC_review_2015-09-16

What would be the best way to get such (updated) information added to the policy, or alternatively, what do you think is the best way to make sure developers will find that information?

@jcrespo @mark This RFC marked a clean start with the entry point at https://www.mediawiki.org/wiki/Development_policy.

The ones attached to this new hierarchy are:

  • Deprecation policy (for MediaWiki core)
  • Merge policy (for Gerrit).

There are also a number of RFCs under way now that might expand this:

In addition to ensuring the documentation reflects consensus around current best practices, I also hope we can better distinguish these three things:

  • development policies (with clear escalation path and point of contact)
  • development guidelines / best practices.
  • processes for specific workflows and/or team interactions. (such as Security reviews, and indeed Schema changes).

No-one has started one yet about Schema changes and/or other db-related requirements, but anyone is welcome to do so! I've kicked one off at T220056: MediaWiki database policy and/or guidelines (2019).

Aklapper removed a subscriber: Anomie.Fri, Oct 16, 5:41 PM