aboutsummaryrefslogtreecommitdiffstats
path: root/DEVELOPERS.md
Commit message (Collapse)AuthorAgeFilesLines
* Codex: Allow a local development version to be usedRoan Kattouw2024-08-221-0/+39
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Developers can use this to test their local version of Codex with MediaWiki by pointing $wgCodexDevelopmentDir to their local clone of the Codex repo, e.g. $wgCodexDevelopmentDir = '/home/yourname/git/codex'; Setting $wgCodexDevelopmentDir affects where the following things come from: - Codex JS/CSS files for the full library - Codex JS/CSS files for code-split chunks, and the manifest.json file that points to them - Icons retrieved by CodexModule::getIcons() - CSS-only icons imported in Less - Design tokens imported in Less Other changes in this patch: - Add CodexModule::makeFilePath() to centralize the repeated path concatenation. This makes it easier to switch out the regular path for the dev mode path. - Replace all uses of $IP (which is deprecated) and MW_INSTALL_PATH in CodexModule with the BaseDirectory config setting. - Make CodexModule::getIcons() reset its static cache if the path to the icons file changes. Without this, it's impossible to make the unit tests pass. - Move the i18n messages code from the CodexModule constructor to getMessages(). It can't be in the constructor because makeFilePath() doesn't work there (it fails because the Config object hasn't been set up yet). - Add a 'mediawiki.skin.codex' import path so that we can stop hard-coding the path to the Codex mixins file. Without this, we can't make the Codex mixins come from the right place in development mode. - Consider $wgCodexDevelopmentDir in setting the cache key for compiled Less code, since changing this setting can change the output of Less compilation (by changing design tokens, icons or mixins). - Add unit tests for (the non-dev mode behavior of) CodexModule::getIcons() and the i18n message key handling. Bug: T314507 Change-Id: I11c6a81a1ba34fe10f4b1c98bf76f0db40c1ce98
* docs: remove deprecated `version` key from docker examplesNovem Linguae2024-05-281-3/+0
| | | | | | | | Follows-up 6ba8efd0a7 (I0f42a2a52f), which removed it from the actual docker-compose.yaml file. Bug: T364815 Change-Id: Iceab6a2b0cca54296cd732d9132df0b6109fd12d
* Add help for a failure when getting startedTuukka Hastrup2024-05-041-0/+4
| | | | Change-Id: If3064abbde9f0d845452153ab460dec919fcface
* DEVELOPERS.md: fix formatting in bullet listSebastian Berlin2024-01-191-3/+3
| | | | Change-Id: I72cff744c29b94e50c01aea86c1f85f49a4687a1
* DEVELOPERS.md: Add note on Docker Desktop Rosetta settingTheresNoTime2023-12-141-0/+4
| | | | | | | | Add a note to disable the use of Rosetta if the user encounters a 503 error. https://phabricator.wikimedia.org/P49617 Change-Id: I8257b3767ab92d4b4ebc1201e712fe00b735bdab
* DEVELOPERS.md: add detail to WSL sectionNovem Linguae2023-12-101-3/+1
| | | | | | | Add detail to Windows Subsystem for Linux (WSL) section of DEVELOPERS.md. Change-Id: I6a67c14e29454473a1ea9d4d3267e6c816e12713
* DEVELOPERS.md: Minor editing and formattingReedy2023-11-241-23/+41
| | | | | | | * Consistently wrap lines * Fix some typos Change-Id: I97d8377c231ce152f5c9cf87e9bb18c82c7de214
* DEVELOPERS.md: reword WSL instructions to include best practicesDatGuy2023-11-211-1/+1
| | | | | Bug: T351758 Change-Id: I7e6d8e0e993053e6e45a5c15f02f7413871d5e55
* DEVELOPERS.md: Corrections for documentation on mounting extension directoriesSebastian Berlin2023-09-071-2/+2
| | | | | | | | * Changed the example to talk about an extension (EventLogging) rather than a skin. * Fixed some wording to make sentences make more sense. Change-Id: I96a49422d4d7dbd14d4bb392dcb78a07a906506f
* Merge "Avoid mentioning tests/phpunit.php in documentation"jenkins-bot2023-07-241-2/+2
|\
| * Avoid mentioning tests/phpunit.php in documentationDaimona Eaytoy2023-07-021-2/+2
| | | | | | | | | | | | | | | | The script should never be used directly, to allow an easier migration to vendor/bin/phpunit. Bug: T90875 Change-Id: I8d0c4c3a9007d50f39a6bef37a0db62fe83de4d7
* | DEVELOPERS.md: make the SQLite directory writableNovem Linguae2023-07-191-0/+5
| | | | | | | | | | | | | | | | This is mentioned at the very bottom of the document, but I think it is also worth a mention higher up. Bug: T341310 Change-Id: I39d44b54715ac7895405ede7c964f1b057702585
* | Merge "DEVELOPERS.md: mention `git clone` and WSL"jenkins-bot2023-07-191-2/+12
|\ \
| * | DEVELOPERS.md: mention `git clone` and WSLNovem Linguae2023-07-101-2/+12
| |/ | | | | | | | | | | | | | | | | | | Mention the first bullet of https://www.mediawiki.org/wiki/MediaWiki-Docker in DEVELOPERS.md. The idea is to get all steps into DEVELOPERS.md, even obvious steps. More beginner friendly. Bug: T341310 Change-Id: Id169594b30cfaa572b1fa3cb0cf30af6c67c8f6b
* / DEVELOPERS.md: fix Docker logspam in WindowsNovem Linguae2023-07-101-1/+9
|/ | | | | | | | | | | | MW_DOCKER_UID= and MW_DOCKER_GID= need to be set to blank to avoid warnings about undeclared variables from appearing in bash. The extra line break at the end of line 63 is intentional. If a Windows user copy pastes the text on lines 50-57 into a file named .env, it may not end in a line break. Bug: T341309 Change-Id: I9ca94f7e5afc3514d9fd4c587112b287478d7ece
* Update DEVELOPERS.md and UPGRADE with new way to use update.phpJon Harald Søby2023-06-161-2/+2
| | | | | | | | | | | | When using the command that this commit changes, the console would give a warning that that way of using update.php is deprecated since 1.40, and that one should use maintenance/run.php instead. Follows up Ibd47e3f29f93238ccd3e607774927e639ba74ace and I2cd89a6a9218dadb1bc6088d1c7e1f2c85642902. Change-Id: Id4bdd7fb0f505d119f8cac574889b06012d5c22a
* Merge "Add Windows-specific instructions in DEVELOPERS.md"jenkins-bot2022-12-141-0/+8
|\
| * Add Windows-specific instructions in DEVELOPERS.mdAlistair31492022-09-281-0/+8
| | | | | | | | | | Bug: T270437,T284569 Change-Id: I4f9346272cc2226c9f7f7cbf3a1eaa149b6c8b74
* | Tell Windows users not to add user and group ID to .envLectrician12022-11-161-1/+1
|/ | | | | | | | DEVELOPERS.md states that the user should run a command to add their user and group id to the .env file when setting up a Docker environment. The command does not work or is required in Windows. Change-Id: I4ff8806fcccd925ff7a3945ac605bb5c854dbbee
* Update Docker instructions for DEVELOPERS.mdMarielle Volz2022-09-061-23/+21
| | | | | | | | | | | | | * `docker-compose` is now deprecated for all OS, replace commands with `docker compose` * `docker-engine`, `docker` packages are now deprecated for linux, remove references and replace with correct package names. * Installing by repo is now much more mature, I don't think it makes sense to preference binaries now - but I've added a direct link to the binaries for those that prefer it, as the current link doesn't go there directly anymore. Change-Id: I64d93fb0f47d31b3a1178521e63b1c9f9b9628a8
* docs: Fix syntax of markdown link in DEVELOPERS.mdTimo Tijhof2022-08-261-2/+2
| | | | | | | | | On GitHub and Phabricator, backtics are not valid inside a link, thus leading to a broken -unlinked- rendering of this text. For example, https://github.com/wikimedia/mediawiki/blob/1.38.2/DEVELOPERS.md Change-Id: Icc5fad9e6a747d0ccee52880597b861bcbc23a79
* docs: Document in DEVELOPERS.md how to stop or restart the thingTimo Tijhof2021-10-121-10/+29
| | | | | | | | It's all great that it's up and running, but how does one stop the containers when you're done with it and want/need to reduce load on the computer, or re-create them after something went wrong? Change-Id: I9ec446d73a5fac41550c19eb83912469cfdb92ee
* docs: Various DEVELOPERS.md improvements about MediaWiki-DockerTimo Tijhof2021-09-291-99/+119
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The overall theme of this patch is to reduce cognitive overhead, and increase confidence and familiarity for new developers. == Intro * Fix phab link, which pointed to an unrelated Docker-Hub tag. * Simplify requirements to "Docker Desktop" for macOS/Windows, as that already includes docker-compose. * Add link to webchat. * Docker "Development" isn't a relevant noun, drop cap. * Phabricator `#mediawiki-docker` felt obscure and internal. Rephrase without the obscure comment syntax hashtag, and indicate that it is about creating tasks (not another chatroom). The term "task" will come in handy once on the other side. * Re-balance paragraph boundaries. == Quickstart * Number sections. This suggests more clearly that each section is needed and in order (not a recipe menu, like the other sections). Also offers a sense of progress and makes it easier to remember where you are. * Move "Requirements" into Quickstart as step 1. * Explain what certain steps are for. Especially steps that are not important or useful to most. For example, Linux users creating an override file, is only relevant for people that will 1) contribute in PHP, 2) and have an elaborate IDE, 3) and want to specifically use the "breakpoint" feature of Xdebug. * Add missing "Done" indication. There was no indication that one is done with the installation or what to expect where/when. == Usage * Flatten sections. * Demonstrate PHPUnit using bash. The common case for install commands is to do them once, and have no desire to understand how they work. The common case for tests, is to run them a lot, run variations on them, inspect results, maybe benefit from tab completion on paths, run a maintenance script, etc. Using the wrapped commands gives people a slow experience with no path to learn or discover the surrounding abilities. Encourage curiousity and graduation to other things in the shell, by starting there from the get go. This makes other commands less complicated and should allow for much on-wiki documentation to be applicable in a straight-forward manner without needing to know the "mediawiki docker version" of any such command. == Modify the environment * Start the extension how-to with a recommendation to follow the existing install instructions of any extension on mediawiki.org. This should avoid surprises since for many extensions the two steps given here will not suffice, and will cause confusion, and it's probably better if we don't aim to cover them all here inline. * Trade brevity for practical and interoperable advice. Instead of using a clever git-clone command with destination override, use the plain one that people would see and copy from elsewhere such as mediawiki.org or Gerrit, etc, and execute it from the relevant subdirectory. Otherwise they'd have to modify two parts of the command and thus need the "mediawiki docker version" of every extension install command. Instead of clever `echo >>` append commands, state to add it to the LocalSettings.php file. It's not as brief, but I think making this not a scary file from the get-go is going to pay off in the long term, especially because you then also likely know how to disable it again (by removing it from where you added it), instead of expecting Linux knowledge and abstraction of these shell concepts. * Add example of how to install an extension. * De-emphasize obscure need to mount extensions from another directory. This shouldn't be something we recommend to people out of the blue as two normal ways to install an extension. Rather, the amount is a solution to a pre-existing problem the person may have. Explain what that problem is and offer it in that context. If people do this as just another option, it's going to cause a lot more problems down the road. == Troubleshooting De-emphasize caching workaround to the Troubleshooting section, and set clear expectations about its impact on speed. Thiis is a debugging mechanism for when caching has broken down. It should not be needed, and for the past 11 years I have not at any point done anything like this other than when directly working on the low-level caching mechanisms themselves, which is a pretty rare thing to do. There are many aggressive caching features in MW, which the linked manual page on mediawiki.org explains how to enable, because they are not enabled by default. The ones enabled by default are mild, and (perhaps by accident) happen to be well-suited for the use case of local development, as they have automatic propagation of changes. Change-Id: I40750c694a75948824a8a35f657747ffec42a704
* Merge "MediaWiki-Docker: Remove injection of MW_SCRIPT_PATH"jenkins-bot2021-09-131-2/+3
|\
| * MediaWiki-Docker: Remove injection of MW_SCRIPT_PATHTimo Tijhof2021-09-111-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Injecting it does nothing other than break the wiki with 404 errors. The only thing that uses it is the install.sh script, which then one-time substitutes it in LocalSettings.php. It isn't used by the mount logic for /var/www/w, and it isn't used by the Apache config in the referenced Docker images either. While the injection is removed, I have kept the following two: 1. It is still set for the docker images so that the env variable can still be read, to allow new additions to the dev images to not have to hardcode it, and to perhaps one day actually support this. It seems useful to retain as abstraction layer from that perspective. 2. It is still part of the recommended `.env` file. For the same reason as the previous point, but not theoretical. Our test tools (Selenium, QUnit, fresh-node, etc.) all expect this env variable for discovery and those tools are not specific to MediaWiki-Docker so they need this indeed. After this change, there remains one weak link, which is someone copying the recommended .env file and then deciding to change MW_SCRIPT_PATH for some reason. What will happen is that the wiki continues to work and identify with "/w", and the only impact is that external tooling will look for their custom path, and not find a wiki there. Bug: T273529 Change-Id: I4aa71f8994810ea0fbe2950958097c223c88916c
* | [Docker] fix typo; 'insted' -> 'instead'MusikAnimal2021-09-101-1/+1
| | | | | | | | | | Follow-Up: I5a73e3e3608edd4d514a0502df7f4631afd55fd8 Change-Id: I5c313c0897ffe7353a44eddd76709ad1014fa4ac
* | Merge "[Docker] Add note about caching to documentation"jenkins-bot2021-09-101-0/+24
|\ \
| * | [Docker] Add note about caching to documentationMusikAnimal2021-09-101-0/+24
| |/ | | | | | | | | | | | | | | | | The default caching is so aggressive that the unbeknownst developer is going to be baffled why changes they make don't seem to have any effect. We should offer a common configuration for development so they can get to developing more quickly. Change-Id: I5a73e3e3608edd4d514a0502df7f4631afd55fd8
* / Added a note outlining a possible fix to docker permission errors.Sai Suman Cherukuwada2021-09-101-0/+11
|/ | | | Change-Id: I6e47627b66e4d925ae20819c9c1dc580b3ae6ca7
* DEVELOPERS.md: Update redirected linksMeno252021-08-231-3/+3
| | | | Change-Id: I16bc53746d46264bee4e45d80dbaddd69812cc9c
* Update DEVELOPERS.mdJeena Huneidi2021-08-181-23/+33
| | | | | | | | | * Removes no-longer needed docker-compose.override.yml directions. * Updates directions for skins/extensions to indicate the skin/extension must be in the core directory or mounted as a volume. Bug: T288456 Change-Id: I0053b44f88b434649b72e9e386331a34b46fa981
* Freenode -> Libera per wikimedia moving from freenode to liberaMacFan40002021-05-201-2/+2
| | | | | Bug: T283247 Change-Id: Iebbb13ac53830a8d77b42bf2954cf80d76d78467
* selenium: Update documentation in DEVELOPERS.mdJared Blumer2021-03-231-5/+1
| | | | | | | | Please note that some tests fail. See T277054. Bug: T277427 Bug: T277054 Change-Id: I136cf19acb31fbdb4cbbaa68f3a41f617a3b1a22
* [docker] Set user/group mapping for all host OS, not just LinuxKosta Harlan2021-01-291-8/+14
| | | | | | | | | | | | | Apparently Docker for Mac (I assume also Docker for Windows) has changed and we now need to set the host user/group mapping to avoid permissions problems in the running container. As a result, we don't need to make Linux users create an override file anymore. Also, update the docker-compose.yml to reference the `.env` file, apparently this explicit reference is required for those values to be read. Bug: T273218 Change-Id: Iaadce5d27d6e973ad02afd5b069646e95b5de0aa
* [docker] split php-fpm and apache containersBrennen Bearnes2021-01-261-26/+73
| | | | | | | | | | | | | | | | | | | | | | | | Adds a mediawiki-web service running Apache, and changes mediawiki service to run only PHP-FPM. Assumes users will continue to run CLI PHP in the mediawiki container. Passes MEDIAWIKI_USER and MEDIAWIKI_PASSWORD into the PHP container as MW_USER and MW_PASS respectively. (The difference should be reconciled in a future patch.) Also passes in MW_SCRIPT_PATH if set. There's still some weirdness here in that MW_SERVER, if set in the .env, isn't used, though MW_PORT is. Adds instructions for XDebug 3.x, clarifies some documentation around environment variables and Xdebug use. See https://gerrit.wikimedia.org/r/c/releng/dev-images/+/622575 for more context. Bug: T245444 Depends-On: I67ed53c4bd8e92a4c506da4aa7ffee79ca2910bb Depends-On: Iab57d34b2012eb9e0271a7d4ec02053f984ccf86 Change-Id: I0cfef6f05a9237f310a85942ee881536288131ae
* [docker] Update developer docs for /w script pathKosta Harlan2020-10-061-3/+3
| | | | | | | Follows-Up: I7801f549c887952f5d092651c2543ace6d56e909 Bug: T261051 Change-Id: Iaead879808f9d66cf341eeedf83ce929d294757b
* [docker] Update working directory to /var/www/html/wKosta Harlan2020-10-011-0/+11
| | | | | | | | | | Also documents configuration changes in DEVELOPERS.md. Depends-On: I5b0ac1cbb1d1a2381eff757a1903bce2dacf09d0 Depends-On: I3d967b610a032625318c5a2d233254f7e7ccbf13 Bug: T261051 Bug: T262392 Change-Id: I7801f549c887952f5d092651c2543ace6d56e909
* [docker] Fix install instructions for WindowsKosta Harlan2020-04-061-5/+10
| | | | | | | Also move Linux host specific bits to the Linux users section. Bug: T246953 Change-Id: I7f4b4b0cbba7b07377d0b8fe050061bf457a5326
* [docker] Use install.sh, add instructions for sameKosta Harlan2020-04-041-9/+1
| | | | | | | | | Updates docker-compose.yml to run stretch-php72-fpm-apache2-xdebug:0.3.0, which will contain a /docker/install.sh. Usage is described in DEVELOPERS.md. Depends-On: Icf7dd0e22e0421cf97de1d7c1d4a44ca14f2190a Bug: T246953 Change-Id: Ib7e6e9b872c284583db3a5e83b310183343b4341
* Merge "[docker] Use a .env file for setting the port and user"jenkins-bot2020-04-011-24/+21
|\
| * [docker] Use a .env file for setting the port and userKosta Harlan2020-04-011-24/+21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | - allows for cleanly overriding host exposed port - easier to override XDebug settings - easier setup for Linux hosts When wikimedia/fresh is updated with https://github.com/wikimedia/fresh/pull/18, we can simplify the Selenium / API testing instructions too (removing the `export` statements). Bug: T246586 Bug: T246588 Change-Id: Ibd266411636ac144789617bb0999c33a83e9e652
* | [docker] Add note for Linux users to manage Docker as non-rootKosta Harlan2020-03-291-2/+2
| | | | | | | | | | | | | | This has come up a few times already with users (T248624#6008494, T246827#5944100) so it would be useful to document the solution here. Change-Id: I7c2fa16fd3f129e03c053935f32ebda3b589b9fe
* | [docker] Add recommendation to install docker-compose binaryKosta Harlan2020-03-161-0/+9
|/ | | | | Bug: T246021 Change-Id: I594adc9946ef2c0ba4de0636acb065cd72b5d073
* MediaWiki-Docker: fix Fresh-Node linksmontehurd2020-03-041-1/+1
| | | | | | | | Removed an extra character preventing the "Fresh" links from being resolved on Github mirrors Bug: T246957 Change-Id: I029d819052c0977dfc45f4566f0179f8969e5649
* [docker] Move documentation for Vector out of XDebug sectionKosta Harlan2020-03-041-13/+13
| | | | | | Change-Id: I0bd839e03e5bc1c8f548610bafb1ed2805cd5b04 Follows-Up: I8f25d21e6f07bb82bb2c93163dda85e26e383d8d Bug: T246360
* DEVELOPERS.md: Remove reference to Docker/RecipesKosta Harlan2020-02-291-7/+5
| | | | | | | Consolidate on a single entrypoint to additional documentation on mediawiki.org Bug: T246433 Change-Id: I8dc003fae2a52eb198eb43b82bc80100f13cf990
* MediaWiki-Docker: document how to use Vector skinŽeljko Filipin2020-02-271-0/+14
| | | | | Bug: T246360 Change-Id: I8f25d21e6f07bb82bb2c93163dda85e26e383d8d
* [docker] Adjust UID/GID variable namesKosta Harlan2020-02-251-4/+4
| | | | | | | | | As noted in the task, UID is a read-only variable by default in Bash. Rather than rely on it existing let's explicitly define MW_DOCKER_(UID/GID) for use with docker-compose.override.yml. Bug: T246020 Change-Id: I768486858bc63393f35c3b89fb783c3845183da5
* Fix broken link syntax in DEVELOPERS.mdMichael Große2020-02-241-1/+1
| | | | | | This trailing ")" broke this and the following link. Change-Id: Ifb0fb3e89a14333f23de87b20db0f4eaa1ec86cd
* Add configuration for Docker based development environmentKosta Harlan2020-02-211-0/+215
This patch introduces a simple docker-compose based development environment with the idea to allow most development use cases for beginning and experienced MediaWiki developers. - PHP and Apache container with XDebug enabled - Support for overriding services with docker-compose override file - Documentation for usage and a documented place for sharing docker-compose overrides and LocalSettings.php configuration snippets for e.g. MySQL, DB replication, Redis, etc Depends-On: I50079cca6a286d8aaea8fd0785be48c80e80271c Bug: T238224 Change-Id: I3b76c1599b1ff32174af5603aadc9f7c7634c98b
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-23 06:37:04 +0000