Hey!
I actively contributed to
https://www.mediawiki.org/wiki/Best_practices_for_extensions in the
past. I reviewed the most recent changes for my WMDE TechWish team and
can say that I'm pretty happy with how the page turned out. Some minor
suggestions, though:
* MUST: extension.json must name the code's
<code>"license-name":</code> according to
https://spdx.org/licenses/.
* MUST: The <code>"config":</code> section in extension.json must
list
all configuration options with their default <code>"value":</code>
and
a brief <code>"description":</code>. Yes, I would seriously make
this
a must, knowing that most extensions currently miss the documentation
part.
* Is it worth asking to remove the <code>"version":</code> from
extension.json when it's not actively used (any more) in the release
process of an extension?
* What about CODE_OF_CONDUCT.md? Isn't this required by now?
* I care a lot about "readable code", but the current sentence is not
very meaningful. I mean, who writes code that is intentionally
_unreadable_? Maybe we can suggest making code _expressive_, so it's
easy to understand for later developers, as well as follow the SOLID
principles?
* What does "standard internationalization systems in MediaWiki" refer
to? The message system is already mentioned above. If there are more
systems we should list them.
* I suggest to add "or use HtmlArmor" to the sentence about wikitext vs. HTML.
* The sentence "Use global MediaWiki configuration such as read-only
mode" leaves me a little puzzled. What is this about? The read-only
mode seems super specific – I never used it for anything. Are there
better examples?
* One place mentions "or stuff". Not sure which "stuff" is meant.
It's
probably better to remove the word.
There is also some discussion about "what if I don't (want to)
comply?" at
https://www.mediawiki.org/wiki/Topic:Wovr2kqb7qwhztwu.
While these are interesting questions, personally I don't think they
should block us from moving forward. I mean, these best practices
exist whether or not all existing code conforms to them, whether or
not they are documented, and whether or not we call the documentation
a "draft". This is just about having them documented. It's not like we
plan to rename the page to "Requirements for extensions". Still it
might be worth adding a sentence like "this is only for extensions
listed on mediawiki.org".
Best
Thiemo