Page MenuHomePhabricator

BoilerPlate extension should show latest coding practices
Open, LowPublic

Description

Besides linters and entry points (T94275), we should put other best practices in BoilerPlate:

  • additional continuous integration:
  • documentation generation: doxygen, jsduck, KSS documentation
    • PD extension help (example), using getOutput->addHelpLink() ?
  • tests: browser tests, phpunit, qunit
  • new MediaWiki features and practices
    • extension.json
    • PSR logging
    • Config interface (getConfig()->get( 'CategoryPagingLimit') instead of $wgCategoryPagingLimit)
    • assert handling

The last set raises the question of whether BoilerPlate master should use only cutting-edge features or demonstrate backwards compatibility with the latest release or LTS release.

Event Timeline

Spage raised the priority of this task from to Normal.
Spage updated the task description. (Show Details)
Spage added a subscriber: Spage.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptApr 24 2015, 2:45 AM
Spage updated the task description. (Show Details)Apr 24 2015, 6:41 AM
Spage set Security to None.

Maybe we need a needs-example-code tag similar to the documentation tag that would remind a feature's developer to update BoilerPlate.

BoilerPlate should have no source code comments on features -- it's a skeleton, not tutorial documentation. Instead developers using BoilerPlate can use git log and git blame to find rationale for any line of code. This means BoilerPlate changes must have sensational commit messages mentioning the related feature commit, any RFC, phab task, etc.

If a developer bases an extension off BoilerPlate, how can she incorporate later updates to BoilerPlate?

Qgil added a subscriber: Qgil.Apr 24 2015, 7:14 AM

Maybe we need a needs-example-code tag similar to the documentation tag that would remind a feature's developer to update BoilerPlate.

It's an interesting idea. Please create a task to request this tag, and we can discuss it there.

BoilerPlate should have no source code comments on features -- it's a skeleton, not tutorial documentation.

Mmm... are you sure about this? What is the problem with a self-explanatory verbose skeleton? Keeping a file in a source code repository in sync with a wiki page would serve a double purpose of theoretical/practical training efficiently, I believe. When you use such skeletons for actually developing a new product, it is normal to go through the code and remove/comment what you won't need.

I mean, you don't need to offer the whole manual there, but it could be useful to have basic comments including URLs where such aspect is explained at length.

Spage added a project: ECT-June-2015.EditedJun 2 2015, 10:25 AM

I think this is worth attempting in June (now July). If we can reorg git repos to make Blueprint a top-level extension it'll make integration easier.

Spage claimed this task.Jun 2 2015, 4:14 PM
Spage moved this task from Backlog to Doing on the ECT-July-2015 board.Jul 27 2015, 8:59 PM
Qgil lowered the priority of this task from Normal to Low.Aug 8 2015, 12:53 PM

Low, as discussed.

Aklapper removed Spage as the assignee of this task.Sep 23 2016, 2:11 PM

Change 371077 had a related patch set uploaded (by Samwilson; owner: Samwilson):
[mediawiki/extensions/BoilerPlate@master] Add new-style configuration values with prefix

https://gerrit.wikimedia.org/r/371077

Change 371077 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Add new-style configuration values with prefix

https://gerrit.wikimedia.org/r/371077

The patch I submitted above is not actually correct; it should not use config_prefix etc. (I'm fixing it now; just noting this here in case I don't.)

Qgil moved this task from To triage to Team radar on the Developer-Advocacy board.

Change 383302 had a related patch set uploaded (by Samwilson; owner: Samwilson):
[mediawiki/extensions/BoilerPlate@master] Move classes into src directory, and remove exclusions for phpcs

https://gerrit.wikimedia.org/r/383302

Change 383302 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Move classes into src directory, and remove exclusions for phpcs

https://gerrit.wikimedia.org/r/383302

merbst added a subscriber: merbst.Jun 15 2018, 3:11 PM

Change 534615 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/BoilerPlate@master] Add unit test example

https://gerrit.wikimedia.org/r/534615

Change 534615 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Add unit test example

https://gerrit.wikimedia.org/r/534615