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.

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).

In T190379#4812689, @Legoktm wrote:

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.

In T190379#4812689, @Legoktm wrote:

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.

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.)

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

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

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.

In T190379#4965370, @Anomie wrote:

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.

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?

I commented some options at https://www.mediawiki.org/w/index.php?title=Topic:Uvtmdzoq11pbeunp&topic_showPostId=ux1cwnyqc09tnuwx#flow-post-ux1cwnyqc09tnuwx

@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:

• T215465: RFC: Require use of common storage abstractions (policy)
• T155395: Create documentation about the proper use of the dependency injection infrastructure in MediaWiki

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).