[Wikitech-l] Re: Best practices for extensions

[Krinkle]

Thanks everyone for sharing thoughts here and on the talk page 
.

A number of clarifications have been made, and some unready/outdated sections 
have for the time being been removed, shortened or replaced with a non-nominal 
reference to a different page (such as Accessibility).

To the best of my knowledge, the remaining points of this best practices guide 
are now reflective of the practices that most MediaWiki extension maintainers 
have been practicing in recent years (both in WMF-deployed extensions and many 
third-party extensions alike). As such, I've marked it as a developer guideline.

There are open discussion topics on the talk page 
 about more 
practices to add, including a topic about Accessibility guidelines 
 (Do we re-incorporate 
some of it? And how? How much do we duplicate? If not, what should we do 
instead?)

-- Timo

On Thu, 27 Jan 2022, at 04:43, Krinkle wrote:
> Hi all,
> 
> You may be familiar with the Best practices for extensions 
>  page on 
> mediawiki.org. It has been marked as a draft since 2017.
> 
> I'd like to polish this page and get it to a state where it would be 
> uncontroversial to label it as "Development guideline 
> ". This would not make 
> it a hard policy. Neither does it imply that it covers all practices in all 
> situations.
> 
> Rather, it would mean that the items that are there now are indeed a part of 
> our current best practices. We would keep it alive through bold 
>  edits and talk page 
> conversations, similar to our Coding conventions 
>  and other such 
> guidelines that we maintain peer to peer and through consensus.
> 
> The reason I've not simply labelled it as such already is because before 
> today I found the document to be out of sync with our actual practices. I 
> have made a number of changes with descriptive edit summaries to bring it in 
> sync with what I percieve to be our best practices; based on how myself and 
> other maintainers perform code review at large, and how we review new 
> extensions prior to deployment.
> 
> All are welcome to fix mistakes, raise questions/concerns on the talk page, 
> on this thread. You're also welcome to message me directly anytime if you 
> prefer.
___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[Ostrzyciel]

Hi Timo,

Thanks for clarifying this.

I would like to also point interested folks to the discussion taking 
place here: https://www.mediawiki.org/wiki/Topic:Wovr2kqb7qwhztwu


I think the MUST/SHOULD/OPTIONAL language was in a large part the 
initial source of my confusion.


Ostrzyciel

On 2/15/22 15:41, Krinkle wrote:

Hi Ostrzyciel. Replies inline.

On Thu, 27 Jan 2022, at 08:15, Ostrzyciel wrote:


Maybe a dumb question – I get a profound impression that this email 
*and* the guidelines are directed at Wikimedia employees, not 
MediaWiki extension developers in general.


...why? I thought that most extensions out there are not managed by 
Wikimedia, right?


These guidelines, and indeed most coding conventions and development 
guidelines, are directed at MediaWiki developers in general. They are 
not merely for WMF-maintained extensions or WMF staff.


Of the 70+ bullet points in the current draft, there are exactly 2 
points specific to WMF, and these are explicitly called out as such to 
avoid confusion (those are about sec/perf review, and stewardship).


The best practices document aims to reflect status quo among MediaWiki 
developers, which includes maintainers of the many MediaWiki hosted in 
Gerrit that aren't WMF-deployed. It is my understanding that by and 
large extensions follow the same coding styles, conventions, and 
guidelines. I also find in practice that volunteers contribute as much 
(if not, more than) staff to the shaping and implementation of these 
guidelines. Although these volunteers do tend to contribute more to 
WMF-deployed extensions, they are not currently staff.


In the latter case – are Wikimedia employees the right group to be 
guiding the discussion around these guidelines?




No. I specifically addressed the email to all/everyone, and all MW 
developers are welcome to participate. Extension maintainers often do 
follow these conventions. But, they are by no means required to. It's 
not a requirement for hosting (unlike e.g. licensing and code of 
conduct), and there are certainly numerous extensions that follow a 
different coding style, or don't follow any (publicly known) guidelines.


There is one line in the TLDR of my email where I called upon tech 
leads among WMDE/WMF staff. I recognise this may have set a confusing 
tone.


-- Timo



On 1/27/22 05:43, Krinkle wrote:
TLDR: Tech leads please review Best practices for extensions 
 on 
mediawiki.org.


Hi all,

You may be familiar with the Best practices for extensions 
 page 
on mediawiki.org. It has been marked as a draft since 2017.


I'd like to polish this page and get it to a state where it would be 
uncontroversial to label it as "Development guideline 
". This would 
not make it a hard policy. Neither does it imply that it covers all 
practices in all situations.


Rather, it would mean that the items that are there now are indeed a 
part of our current best practices. We would keep it alive through 
bold  edits and 
talk page conversations, similar to our Coding conventions 
 and 
other such guidelines that we maintain peer to peer and through 
consensus.


The reason I've not simply labelled it as such already is because 
before today I found the document to be out of sync with our actual 
practices. I have made a number of changes with descriptive edit 
summaries to bring it in sync with what I percieve to be our best 
practices; based on how myself and other maintainers perform code 
review at large, and how we review new extensions prior to deployment.


All are welcome to fix mistakes, raise questions/concerns on the 
talk page, on this thread. You're also welcome to message me 
directly anytime if you prefer.


If you consider yourself familiar with our practices and/or lead and 
mentor other engineers, please take a minute to review the page and 
consider whether the items reflect your current understanding and 
judgement.


--
Timo Tijhof,
Principal Engineer,
Wikimedia Performance Team.



___
Wikitech-l mailing list --wikitech-l@lists.wikimedia.org
To unsubscribe send an email towikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[Krinkle]

Hi Ostrzyciel. Replies inline.

On Thu, 27 Jan 2022, at 08:15, Ostrzyciel wrote:
> Maybe a dumb question – I get a profound impression that this email *and* the 
> guidelines are directed at Wikimedia employees, not MediaWiki extension 
> developers in general.
> 
> ...why? I thought that most extensions out there are not managed by 
> Wikimedia, right?

These guidelines, and indeed most coding conventions and development 
guidelines, are directed at MediaWiki developers in general. They are not 
merely for WMF-maintained extensions or WMF staff.

Of the 70+ bullet points in the current draft, there are exactly 2 points 
specific to WMF, and these are explicitly called out as such to avoid confusion 
(those are about sec/perf review, and stewardship).

The best practices document aims to reflect status quo among MediaWiki 
developers, which includes maintainers of the many MediaWiki hosted in Gerrit 
that aren't WMF-deployed. It is my understanding that by and large extensions 
follow the same coding styles, conventions, and guidelines. I also find in 
practice that volunteers contribute as much (if not, more than) staff to the 
shaping and implementation of these guidelines. Although these volunteers do 
tend to contribute more to WMF-deployed extensions, they are not currently 
staff.

> In the latter case – are Wikimedia employees the right group to be guiding 
> the discussion around these guidelines?
> 

No. I specifically addressed the email to all/everyone, and all MW developers 
are welcome to participate. Extension maintainers often do follow these 
conventions. But, they are by no means required to. It's not a requirement for 
hosting (unlike e.g. licensing and code of conduct), and there are certainly 
numerous extensions that follow a different coding style, or don't follow any 
(publicly known) guidelines.

There is one line in the TLDR of my email where I called upon tech leads among 
WMDE/WMF staff. I recognise this may have set a confusing tone.

-- Timo


> On 1/27/22 05:43, Krinkle wrote:
>> TLDR: Tech leads please review Best practices for extensions 
>>  on 
>> mediawiki.org.
>> 
>> Hi all,
>> 
>> You may be familiar with the Best practices for extensions 
>>  page on 
>> mediawiki.org. It has been marked as a draft since 2017.
>> 
>> I'd like to polish this page and get it to a state where it would be 
>> uncontroversial to label it as "Development guideline 
>> ". This would not 
>> make it a hard policy. Neither does it imply that it covers all practices in 
>> all situations.
>> 
>> Rather, it would mean that the items that are there now are indeed a part of 
>> our current best practices. We would keep it alive through bold 
>>  edits and talk page 
>> conversations, similar to our Coding conventions 
>>  and other 
>> such guidelines that we maintain peer to peer and through consensus.
>> 
>> The reason I've not simply labelled it as such already is because before 
>> today I found the document to be out of sync with our actual practices. I 
>> have made a number of changes with descriptive edit summaries to bring it in 
>> sync with what I percieve to be our best practices; based on how myself and 
>> other maintainers perform code review at large, and how we review new 
>> extensions prior to deployment.
>> 
>> All are welcome to fix mistakes, raise questions/concerns on the talk page, 
>> on this thread. You're also welcome to message me directly anytime if you 
>> prefer.
>> 
>> If you consider yourself familiar with our practices and/or lead and mentor 
>> other engineers, please take a minute to review the page and consider 
>> whether the items reflect your current understanding and judgement.
>> 
>> --
>> Timo Tijhof,
>> Principal Engineer,
>> Wikimedia Performance Team.
___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[Sam Wilson]

The 'version' key isn't used in the release process, but it is still 
displayed in Special:Version. Although, I totally agree with removing 
it, as it often isn't updated, and so just ends up being confusing.


The other thing I was wondering about adding was that non-Gerrit 
extensions should be added to the list in 
https://github.com/MWStake/nonwmf-extensions so that they can be used in 
things like the code search tool  and 
extjsonuploader . That sort of goes 
against the first two points on the page (about how extensions must use 
Phabricator and Gerrit), so I'm not sure.



On 1/2/22 00:59, Thiemo Kreuz wrote:

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
"license-name": according tohttps://spdx.org/licenses/.

* MUST: The "config": section in extension.json must list
all configuration options with their default "value": and
a brief "description":. Yes, I would seriously make this
a must, knowing that most extensions currently miss the documentation
part.

* Is it worth asking to remove the "version": 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?" athttps://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
___
Wikitech-l mailing list --wikitech-l@lists.wikimedia.org
To unsubscribe send an email towikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[K. Peachey]

On Tue, 1 Feb 2022, 3:00 am Thiemo Kreuz,  wrote:
> … snip …
> * What about CODE_OF_CONDUCT.md? Isn't this required by now?

Historically (aka when the file first got mass added) there were
arguments that ensured about that, From memory the outcome was that
the file is not required but none the less any code in our Gerrit
instance (and gitlab) is automatically covered and there is nil
exclusions to that
___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[Thiemo Kreuz]

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
"license-name": according to https://spdx.org/licenses/.

* MUST: The "config": section in extension.json must list
all configuration options with their default "value": and
a brief "description":. Yes, I would seriously make this
a must, knowing that most extensions currently miss the documentation
part.

* Is it worth asking to remove the "version": 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
___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/

[Wikitech-l] Re: Best practices for extensions

[Ostrzyciel]

Hi,

Maybe a dumb question – I get a profound impression that this email 
*and* the guidelines are directed at Wikimedia employees, not MediaWiki 
extension developers in general.
...why? I thought that most extensions out there are not managed by 
Wikimedia, right?


It's just that as someone who wrote several extensions I'm quite puzzled 
by most of the non-technical guidelines there.


So, please clarify if these are guidelines for "Wikimedia extensions" or 
"MediaWiki extensions". In the latter case – are Wikimedia employees the 
right group to be guiding the discussion around these guidelines?


Ostrzyciel

On 1/27/22 05:43, Krinkle wrote:
TLDR: Tech leads please review Best practices for extensions 
 on 
mediawiki.org.


Hi all,

You may be familiar with the Best practices for extensions 
 page on 
mediawiki.org. It has been marked as a draft since 2017.


I'd like to polish this page and get it to a state where it would be 
uncontroversial to label it as "Development guideline 
". This would 
not make it a hard policy. Neither does it imply that it covers all 
practices in all situations.


Rather, it would mean that the items that are there now are indeed a 
part of our current best practices. We would keep it alive through 
bold  edits and talk 
page conversations, similar to our Coding conventions 
 and 
other such guidelines that we maintain peer to peer and through consensus.


The reason I've not simply labelled it as such already is because 
before today I found the document to be out of sync with our actual 
practices. I have made a number of changes with descriptive edit 
summaries to bring it in sync with what I percieve to be our best 
practices; based on how myself and other maintainers perform code 
review at large, and how we review new extensions prior to deployment.


All are welcome to fix mistakes, raise questions/concerns on the talk 
page, on this thread. You're also welcome to message me directly 
anytime if you prefer.


If you consider yourself familiar with our practices and/or lead and 
mentor other engineers, please take a minute to review the page and 
consider whether the items reflect your current understanding and 
judgement.


--
Timo Tijhof,
Principal Engineer,
Wikimedia Performance Team.

___
Wikitech-l mailing list --wikitech-l@lists.wikimedia.org
To unsubscribe send an email towikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/___
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/