Topic on Talk:Best practices for extensions

Jump to navigation Jump to search

Location for source JS files and JS build artifacts

PMiazga (WMF) (talkcontribs)

The Best practices document states that the `/src` folder is a place only for PHP files. The problem I noticed is that some extensions put more detail to the Javascript side, for example MobileFrontend or PagePreviews use lots of JS code. Further more, those extensions use Webpack - building step that transforms src js files into compiled/minified code.

The webpack best practices state that the source code should go to `/src` folder, and the compilation artifacts to `/dist`, but that doesn't match the MediaWiki practices which states that JS code should live in the 'resources'.

Additionally, having a possibility to keep "new" js files in different place than `/resources` folder gives us an easy way to see which parts of the JS code are already ported, and which waits for the refactor.

Currently, Popups and MobileFrontend extensions have the JS code located in the `/src` folder, and the compilation artifacts stored in the `/resources/dist` folder.

Niedzielski (talkcontribs)

Keeping resources/dist, moving PHP to src/php, and moving JavaScript to src/js works for me. Alternatively, src/server and src/client also work.

NRay (WMF) (talkcontribs)

+1 to both @PMiazga (WMF) and @Niedzielski. Outside of mediawiki, `/src` is a very common convention for JS. If PHP follows that convention as well, @Niedzielski suggestion might be best.

X-Savitar (talkcontribs)

Thanks @PMiazga (WMF) for starting this thread. Conventionally, I see a lot of code bases using `src/` for putting human readable code but over the years, MediaWiki and extensions have adopted and used `includes/` for this purpose. I'm not sure exactly why `includes/` and the reasoning behind it but it would be good to know.

That being said, there are 3 questions in my mind right now;

1. Will making changes to the directory structure a little bit (moving from `includes/` to `src/`) reduce cognitive load for current developers and its community at large? It's kinda hard for 10 years MW developers to make this kind of switch?

2. Will this migration/change impact wikis (Wikimedia or others) configuration wise? How good or bad will the impact be?

3. Will the new directory structure be easier for new developers to adopt and navigate the codebase?

While I've asked those questions, I'll lean towards adopting the `src/` directory structure for placing our source code files (PHP + JS) as it's pretty much used almost everywhere.

In addition, @Niedzielski also raised a good point about `src/php` and `src/js`. Could this be an RfC for more people to give ideas and discuss about it?

Reply to "Location for source JS files and JS build artifacts"