## 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.
2. 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](https://www.mediawiki.org/wiki/Gerrit/%2B2#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](https://www.mediawiki.org/wiki/Deprecation_policy).
* Those with merge rights to MediaWiki core or a Wikimedia-deployed extensions/skin for MediaWiki, must follow the [+2 policy](https://www.mediawiki.org/wiki/Gerrit/%2B2) for all changes they merge.
I propose we also prepend the [RFC 2119](https://tools.ietf.org/html/rfc2119) blurb, and explicitly state that normative changes must follow the [RFC process](https://www.mediawiki.org/wiki/Requests_for_comment/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:
* [Category:MediaWiki development policies](https://www.mediawiki.org/wiki/Category:MediaWiki_development_policies)
* [Development policy](https://www.mediawiki.org/wiki/Development_policy) (Status: "Official". Last major revision before 2012)
* [Deprecation policy](https://www.mediawiki.org/wiki/Deprecation_policy) (Status: RFC-Approved. Last revised in 2017)
* [Security policy](https://www.mediawiki.org/wiki/Security_for_developers) (Status: "Official". Last major revision in 2012)
* [Architecture guidelines](https://www.mediawiki.org/wiki/Architecture_guidelines) (Status: Draft. Last major revision in 2014)
* [Gerrit/+2](https://www.mediawiki.org/wiki/Gerrit/%2B2) (Status: "Official". Last major change in 2013)
* Misc bits:
* [Database optimization](https://www.mediawiki.org/wiki/Database_optimization) (Linked from "Development policy" and "Gerrit/+2")
* [Database transactions](https://www.mediawiki.org/wiki/Database_transactions)
* https://www.mediawiki.org/wiki/Manual:Coding_conventions
* "RFC: Deprecate use of serialize()" – T161647
* <https://www.mediawiki.org/wiki/Best_practices_for_extensions>
* [TechCom's Platform Architecture Principles](https://www.mediawiki.org/wiki/Wikimedia_Technical_Committee/MediaWiki_Platform_Architecture_Principles)