Page MenuHomePhabricator

List of best practices for Toolforge tools
Open, MediumPublic

Description

Best practices lists are a great way to orient new developers and make sure they are aware of all the things they should be aware of. We have a great best practices list for extensions, but nothing similar for Toolforge tools; it would be great to have one.

Event Timeline

We do have https://commons.wikimedia.org/wiki/File:FLOSS_Best_Practices_for_Bots_and_Tools_poster.pdf (via https://github.com/bd808/floss-best-practices-for-bots-and-tools-poster/ via T169919) but I agree a more detailed listing would be good. Converting that image into onwiki (searchable) text might be a good first step?

The three high-level areas to cover:

  • links to language-specific best practices (such as PHP The Right Way or the PHP security checklist - you can find a zillion best practices lists by googling but most of them are not actually very good so some prefiltering would be helpful for new developers who don't yet have the experience to do it themselves)
  • how to implement Wikimedia values (privacy, i18n, being community-driven...)
  • Toolforge ecosystem (e.g. how to integrate with Phabricator, how to do monitoring)
bd808 subscribed.

The https://wikitech.wikimedia.org/wiki/Help:Toolforge/Developing page would be the right place to start organizing this collection of information.

The three high-level areas to cover:

  • links to language-specific best practices (such as PHP The Right Way or the PHP security checklist - you can find a zillion best practices lists by googling but most of them are not actually very good so some prefiltering would be helpful for new developers who don't yet have the experience to do it themselves)

I'm a bit torn on the idea of trying to curate collections of links to general best practices for language X as a specific part of Toolforge help documentation. I see the benefit for "one stop shopping", but unless we have actual users of the various languages actively engaged in maintaining the documentation things are likely to get dated in various ways pretty quickly. We have a hard time just covering things like pywikibot that have strong user communities of their own.

  • how to implement Wikimedia values (privacy, i18n, being community-driven...)

I like this idea a lot. This seems like content that really should already exist on mediawiki.org somewhere, but it is probably scattered around and found in essay spaces more than anywhere else.

  • Toolforge ecosystem (e.g. how to integrate with Phabricator, how to do monitoring)

This is sort of the point of the sum of all of the Help:Toolforge pages. ;)

We do have https://commons.wikimedia.org/wiki/File:FLOSS_Best_Practices_for_Bots_and_Tools_poster.pdf (via https://github.com/bd808/floss-best-practices-for-bots-and-tools-poster/ via T169919) but I agree a more detailed listing would be good. Converting that image into onwiki (searchable) text might be a good first step?

The long form version of the poster is https://wikitech.wikimedia.org/wiki/User:BryanDavis/Developing_community_norms_for_critical_bots_and_tools. I really wish I had been given the chance to present this material at Wikimania as a full presentation rather than a poster in a narrow corridor that you had to deliberately walk down to see. Telling developers these ideas is useful, but getting the end-user communities to demand them is really what is needed.

I'm a bit torn on the idea of trying to curate collections of links to general best practices for language X as a specific part of Toolforge help documentation. I see the benefit for "one stop shopping", but unless we have actual users of the various languages actively engaged in maintaining the documentation things are likely to get dated in various ways pretty quickly. We have a hard time just covering things like pywikibot that have strong user communities of their own.

I agree in general, but the problem with pywikibot is lack of documentation in the first place, not that there is no one would know where to find the documentation and link to it. For popular languages there is an abundance of relevant information. I don't think we should try to maintain "language X best practices" lists, but when there is already a decent one out there, we should link to it.

This is sort of the point of the sum of all of the Help:Toolforge pages. ;)

Saying "for development, see all wikitech pages" is not so helpful though. I was thinking of a link of lists that developers can use to verify they found all the relevant pages.

Tgr added a project: User-Tgr.

I will probably need this for Outreachy.

Changing priority to normal for now. Will be reviewing as part of an effort to improve Toolforge/Cloud Services documentation.