2019-11-13 15:34:03 +00:00
# MediaWiki Developers
Welcome to the MediaWiki community! Please see [How to become a MediaWiki
hacker](https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker) for
general information on contributing to MediaWiki.
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
## Development environment
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
MediaWiki provides an extendable local development environment based on Docker Compose. This environment provides PHP,
Apache, Xdebug and a SQLite database.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
**Do not use the development environment to serve a public website! Bad things would happen!**
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
More documentation, examples, and configuration recipes are available at [mediawiki.org/wiki/MediaWiki-Docker][mw-docker].
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
Support is available on the [Libera IRC network][libera-home] in the [#mediawiki channel][libera-webchat], and on
Phabricator by creating tasks with the [MediaWiki-Docker][mw-docker-phab] tag.
2019-11-13 15:34:03 +00:00
2020-02-29 21:59:38 +00:00
[mw-docker]: https://www.mediawiki.org/wiki/MediaWiki-Docker
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
[mw-docker-phab]: https://phabricator.wikimedia.org/tag/mediawiki-docker/
[libera-home]: https://libera.chat/
2022-08-25 19:17:00 +00:00
[libera-webchat]: https://web.libera.chat/#mediawiki
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
## Quickstart
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### 1. Requirements
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
You'll need to have Docker installed:
* [Docker Desktop][docker-install] for macOS or Windows.
2022-09-06 10:27:49 +00:00
* [Docker engine][docker-linux] for Linux.
2019-11-13 15:34:03 +00:00
2021-08-21 21:12:02 +00:00
[docker-install]: https://docs.docker.com/get-docker/
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
[docker-linux]: https://docs.docker.com/engine/install/
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
**Linux users**:
2020-03-16 13:03:26 +00:00
2022-09-06 10:27:49 +00:00
* We recommend installing `docker-ce` , `docker-ce-cli` , `containerd.io` , and `docker-compose-plugin` by [downloading the server
2023-07-02 15:33:48 +00:00
releases][dc-release] for your distribution rather than Docker Desktop. You can also install the [binaries][dc-binaries].
2020-09-09 12:27:11 +00:00
* Follow the instructions to ["Manage Docker as a non-root user"][dc-non-root]
2022-09-06 10:27:49 +00:00
[dc-release]: https://docs.docker.com/engine/install/
[dc-binaries]: https://docs.docker.com/engine/install/binaries/
2020-09-09 12:27:11 +00:00
[dc-non-root]: https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user
2020-03-16 13:03:26 +00:00
2023-07-11 00:53:27 +00:00
**Windows users**:
2023-11-22 10:19:54 +00:00
Running Docker from a Windows terminal and using the Windows file system will result in MediaWiki being very slow. For Windows 10 and higher, we recommend configuring Docker and Windows to use the [Windows Subsystem for Linux (WSL) ](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux ). Turn on WSL in your Windows settings, then run the following commands: `wsl --install -d ubuntu` and `wsl --set-version ubuntu 2` . Then go into Docker -> Settings -> General -> tick "Use the WSL 2 based engine", then go into Docker -> Settings -> Resources -> WSL Integration -> tick "Ubuntu". `git clone` the mediawiki repository into a WSL folder such as `home/yourusername/mediawiki` so that the files are inside WSL. Then you can run most of the commands in this tutorial outside of WSL, by opening PowerShell, navigating to the WSL directory with `cd \\wsl.localhost\Ubuntu\home\yourusername\mediawiki` , and executing shell commands as normal. To access WSL from PowerShell (rare but may be needed sometimes), you can use the command `ubuntu` to turn a PowerShell console into a WSL console. To navigate to WSL folders in [File Explorer ](https://en.wikipedia.org/wiki/File_Explorer ), show the Navigation Pane, then towards the bottom, look for "Linux" (it will be close to "This PC").
2023-07-11 00:53:27 +00:00
2023-12-14 11:34:15 +00:00
**Mac users**:
If you're using Docker Desktop and have the `Use Rosetta for x86/amd64 emulation on Apple Silicon` setting enabled, you may encounter an issue where loading the wiki results in a blank page or a 503 error. To resolve this, disable the setting and restart Docker Desktop. See [this page ](https://phabricator.wikimedia.org/P49617 ) for more information.
2023-07-11 00:53:27 +00:00
### 2. Download MediaWiki files
2023-11-24 23:46:43 +00:00
Download the latest MediaWiki files to your computer. One way to download the latest alpha version of MediaWiki is to
[install git ](https://git-scm.com/ ), open a shell, navigate to the directory where you want to save the files, then type
`git clone https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki` .
2023-07-11 00:53:27 +00:00
2023-11-24 23:46:43 +00:00
Optional: If you plan to submit patches to this repository, you will probably want to [create a Gerrit account ](https://wikitech.wikimedia.org/wiki/Help:Create_a_Wikimedia_developer_account ),
then type `git remote set-url origin ssh://YOUR-GERRIT-USERNAME-HERE@gerrit.wikimedia.org:29418/mediawiki/core` ,
replacing YOUR-GERRIT-USERNAME-HERE with your Gerrit username. Please see the official
[MediaWiki Gerrit tutorial ](https://www.mediawiki.org/wiki/Gerrit/Tutorial ) for more information.
2023-07-11 00:53:27 +00:00
### 3. Prepare `.env` file
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
Using a text editor, create a `.env` file in the root of the MediaWiki core repository, and copy these contents into
that file:
2020-03-04 21:15:31 +00:00
2020-09-09 12:27:11 +00:00
```sh
2020-10-06 08:56:18 +00:00
MW_SCRIPT_PATH=/w
2020-03-04 21:15:31 +00:00
MW_SERVER=http://localhost:8080
2020-09-09 12:27:11 +00:00
MW_DOCKER_PORT=8080
2020-03-04 21:15:31 +00:00
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
2020-09-09 12:27:11 +00:00
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true
2020-03-04 21:15:31 +00:00
```
2019-11-13 15:34:03 +00:00
2023-07-11 01:40:48 +00:00
Windows users: Run the following command to add a blank user ID and group ID to your `.env` file:
```sh
echo "
MW_DOCKER_UID=
MW_DOCKER_GID=" >> .env
```
Non-Windows users: Run the following command to add your user ID and group ID to your `.env` file:
2021-08-18 18:47:29 +00:00
```sh
echo "MW_DOCKER_UID=$(id -u)
MW_DOCKER_GID=$(id -g)" >> .env
```
2023-11-24 23:46:43 +00:00
Linux users: If you'd like to use Xdebug features inside your IDE, then create a `docker-compose.override.yml` file as
well:
2020-03-04 21:15:31 +00:00
2019-11-13 15:34:03 +00:00
```yaml
services:
mediawiki:
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
# For Linux: This extra_hosts section enables Xdebug-IDE communication:
2020-09-09 12:27:11 +00:00
extra_hosts:
- "host.docker.internal:host-gateway"
2020-04-06 19:52:44 +00:00
```
2023-07-11 00:53:27 +00:00
### 4. Create the environment
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
* Start the containers:
```sh
2022-09-06 10:27:49 +00:00
docker compose up -d
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
```
2023-11-24 23:46:43 +00:00
The "up" command makes sure that the PHP and webserver containers are running (and any others in the
`docker-compose.yml` file). It is safe to run at any time, and will do nothing if the containers are already running.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
The first time, it may take a few minutes to download new Docker images.
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
The `-d` argument stands for "detached" mode, which run the services in the background. If you suspect a problem with
2024-01-19 08:11:25 +00:00
one of the services, you can run it without `-d` to follow the server logs directly from your terminal. You don't have
to stop the services first, if you ran it with `-d` and then without, you'll get connected to the already running
containers including a decent back scroll of server logs.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
Note that MediaWiki debug logs go to `/cache/*.log` files (not sent to docker).
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
* Install PHP dependencies from Composer:
```sh
2022-09-06 10:27:49 +00:00
docker compose exec mediawiki composer update
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
```
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
* Install MediaWiki:
```sh
2022-09-06 10:27:49 +00:00
docker compose exec mediawiki /bin/bash /docker/install.sh
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
```
2022-09-28 22:02:55 +00:00
Windows users: make sure you run the above command in PowerShell as it does not work in Bash.
2019-11-13 15:34:03 +00:00
2023-07-11 01:23:54 +00:00
* Windows users: Make sure to set the SQLite directory to be writable.
```sh
docker compose exec mediawiki chmod -R o+rwx cache/sqlite
```
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
Done! The wiki should now be available for you at < http: / / localhost:8080 > .
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
## Usage
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Running commands
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
You can use `docker compose exec mediawiki bash` to open a Bash shell in the
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
MediaWiki container. You can then run one or more commands as needed and stay
within the container shell.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
You can also run a single command in the container directly from your host
2023-06-16 12:20:05 +00:00
shell, for example: `docker compose exec mediawiki php maintenance/run.php update` .
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### PHPUnit
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
Run a single PHPUnit file or directory:
2019-11-13 15:34:03 +00:00
```sh
2022-09-06 10:27:49 +00:00
docker compose exec mediawiki bash
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
instance:/w$ cd tests/phpunit
2023-07-02 15:33:48 +00:00
instance:/w/tests/phpunit$ composer phpunit -- path/to/my/test/
2019-11-13 15:34:03 +00:00
```
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
See [PHPUnit on mediawiki.org][phpunit-testing] for more examples.
2019-11-13 15:34:03 +00:00
2021-08-21 21:12:02 +00:00
[phpunit-testing]: https://www.mediawiki.org/wiki/Manual:PHP_unit_testing/Running_the_tests
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Selenium
2019-11-13 15:34:03 +00:00
You can use [Fresh][fresh] to run [Selenium in a dedicated
container][selenium-dedicated]. Example usage:
```sh
fresh-node -env -net
npm ci
2021-03-15 01:29:26 +00:00
npm run selenium-test
2019-11-13 15:34:03 +00:00
```
2021-08-21 21:12:02 +00:00
[selenium-dedicated]: https://www.mediawiki.org/wiki/Selenium/Getting_Started/Run_tests_using_Fresh
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### API Testing
2019-11-13 15:34:03 +00:00
You can use [Fresh][fresh] to run [API tests in a dedicated
container][api-dedicated]. Example usage:
```sh
export MW_SERVER=http://localhost:8080/
2020-10-06 08:56:18 +00:00
export MW_SCRIPT_PATH=/w
2019-11-13 15:34:03 +00:00
export MEDIAWIKI_USER=Admin
export MEDIAWIKI_PASSWORD=dockerpass
fresh-node -env -net
# Create .api-testing.config.json as documented on
# https://www.mediawiki.org/wiki/MediaWiki_API_integration_tests
npm ci
npm run api-testing
```
2020-03-04 23:46:06 +00:00
[fresh]: https://github.com/wikimedia/fresh
2019-11-13 15:34:03 +00:00
[api-dedicated]: https://www.mediawiki.org/wiki/MediaWiki_API_integration_tests
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
## Modify the development environment
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
You can override the default services from a `docker-compose.override.yml`
file, and make use of those overrides by changing `LocalSettings.php` .
2020-02-29 21:59:38 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
Example overrides and configurations can be found under
[MediaWiki-Docker on mediawiki.org][mw-docker].
2019-11-13 15:34:03 +00:00
2022-09-06 10:27:49 +00:00
After updating `docker-compose.override.yml` , run `docker compose down`
followed by `docker compose up -d` for changes to take effect.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Install extra packages
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
If you need root on the container to install system packages with `apt-get` for
troubleshooting, you can open a shell as root with
2022-09-06 10:27:49 +00:00
`docker compose exec --user root mediawiki bash` .
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Install extensions and skins
MediaWiki-Docker: Remove injection of MW_SCRIPT_PATH
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
2021-09-10 22:29:28 +00:00
2023-11-24 23:46:43 +00:00
To install an extension or skin, follow the instructions of the mediawiki.org
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
page for the extension or skin in question, and look for any dependencies
or additional steps that may be needed.
2020-02-27 16:58:17 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
For most extensions, only two steps are needed: download the code to the
right directory, and then enable the component from `LocalSettings.php` .
2020-02-27 16:58:17 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
To install the Vector skin:
2020-02-27 16:58:17 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
1. Clone the skin:
2021-08-18 18:47:29 +00:00
```sh
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
cd skins/
git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector
2021-08-18 18:47:29 +00:00
```
2020-02-27 16:58:17 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
2. Enable the skin, by adding the following to `LocalSettings.php` :
```php
wfLoadSkin( 'Vector' );
```
To install the EventLogging extension:
1. Clone the extension repository:
```sh
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventLogging
```
2023-11-24 23:46:43 +00:00
Alternatively, if you have extension repositories elsewhere on disk, mount each one as an overlapping volume in
`docker-compose.override.yml` . This is comparable to a symlink, but those are not well-supported in Docker.
2021-08-18 18:47:29 +00:00
```yaml
services:
mediawiki:
volumes:
2023-09-07 07:20:29 +00:00
- ~/Code/EventLogging:/var/www/html/w/extensions/EventLogging:cached
2021-08-18 18:47:29 +00:00
```
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
2. Enable the extension, by adding the following to `LocalSettings.php` :
```php
wfLoadExtension( 'EventLogging' );
2021-08-18 18:47:29 +00:00
```
2020-02-27 16:58:17 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Xdebug
2020-09-09 12:27:11 +00:00
By default, you will need to set `XDEBUG_TRIGGER=1` in the GET/POST, or as an
environment variable, to turn on Xdebug for a request.
You can also install a browser extension for controlling whether Xdebug is
2023-11-24 23:46:43 +00:00
active. See the [official Xdebug Step Debugging][step-debug], particularly the
2020-09-09 12:27:11 +00:00
"Activating Step Debugging" section, for more details.
2020-03-04 21:21:04 +00:00
2020-09-09 12:27:11 +00:00
[step-debug]: https://xdebug.org/docs/step_debug
If you wish to run Xdebug on every request, you can set
`start_with_request=yes` in `XDEBUG_CONFIG` in your .env file:
```
XDEBUG_CONFIG=start_with_request=yes
```
2023-11-24 23:46:43 +00:00
You can pass any of Xdebug's configuration values in this variable. For example:
2020-03-04 21:21:04 +00:00
2020-03-04 21:15:31 +00:00
```
2020-09-09 12:27:11 +00:00
XDEBUG_CONFIG=client_host=192.168.42.34 client_port=9000 log=/tmp/xdebug.log
2020-03-04 21:21:04 +00:00
```
2020-09-09 12:27:11 +00:00
This shouldn't be necessary for basic use cases, but see [the Xdebug settings
documentation](https://xdebug.org/docs/all_settings) for available settings.
2024-05-02 03:27:22 +00:00
### Codex
You can use your local version of Codex instead of the one bundled with MediaWiki. This is useful
when testing how changes in Codex affect Codex-based features in MediaWiki.
1. Clone the Codex repository and build Codex, if you haven't done this already:
```sh
cd ../
git clone https://gerrit.wikimedia.org/r/design/codex
cd codex
npm run build-all
```
2. If your clone of the Codex repository is outside of the MediaWiki directory (this is common),
add the following to your `docker-compose.override.yml` . Replace `~/git/codex` with the path to
your Codex clone.
```yaml
services:
mediawiki:
volumes:
- ~/git/codex:/var/www/html/w/codex:cached
```
3. To apply the change to `docker-compose.override.yml` , you have to recreate the environment:
```sh
docker compose down
docker compose up -d
```
4. Enable Codex development mode by adding the following to the bottom of `LocalSettings.php` :
```php
$wgCodexDevelopmentDir = MW_INSTALL_PATH . '/codex';
```
To disable Codex development mode and use the regular version of Codex, delete or comment out
this line.
5. Every time you make a change to your local copy of Codex (or download a Gerrit change), you
have to rerun Codex's build process for these changes to take effect. To do this, run
`npm run build-all` in the Codex directory.
2021-09-26 20:27:10 +00:00
### Stop or recreate environment
2023-11-24 23:46:43 +00:00
Stop the environment, perhaps to reduce the load when working on something
2021-09-26 20:27:10 +00:00
else. This preserves the containers, to be restarted later quickly with
2022-09-06 10:27:49 +00:00
the `docker compose up -d` command.
2021-09-26 20:27:10 +00:00
```sh
2022-09-06 10:27:49 +00:00
docker compose stop
2021-09-26 20:27:10 +00:00
```
Destroy and re-create the environment. This will delete the containers,
including any logs, caches, and other modifications you may have made
via the shell.
```sh
2022-09-06 10:27:49 +00:00
docker compose down
docker compose up -d
2021-09-26 20:27:10 +00:00
```
### Re-install the database
To empty the wiki database and re-install it:
* Remove or rename the `LocalSettings.php` file.
* Delete the `cache/sqlite` directory.
* Re-run the "Install MediaWiki database" command.
2023-11-24 23:46:43 +00:00
You can now restore or copy over any modifications you had in your previous `LocalSettings.php` file.
And if you have any additional extensions installed that required a database table, then also run:
`docker compose exec mediawiki php maintenance/run.php update` .
2021-09-26 20:27:10 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
## Troubleshooting
### Caching
If you suspect a change is not applying due to caching, start by [hard
refreshing](https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache) the browser.
2021-08-05 15:47:55 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
If that doesn't work, you can narrow it down by disabling various server-side
caching layers in `LocalSettings.php` , as follows:
2021-08-05 15:47:55 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
```php
2021-08-05 15:47:55 +00:00
$wgMainCacheType = CACHE_NONE;
$wgMessageCacheType = CACHE_NONE;
$wgParserCacheType = CACHE_NONE;
$wgResourceLoaderMaxage = [
'versioned' => 0,
'unversioned' => 0
];
```
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
The default settings of MediaWiki are such that caching is smart and changes
propagate immediately. Using the above settings may slow down your wiki
significantly. Especially on macOS and Windows, where Docker Desktop uses
a VM internally and thus has longer file access times.
2021-08-05 15:47:55 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
See [Manual:Caching][manual-caching] on mediawiki.org for more information.
2021-08-05 15:47:55 +00:00
[manual-caching]: https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Caching
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Xdebug ports
2020-09-09 12:27:11 +00:00
Older versions of Xdebug used port 9000, which could conflict with php-fpm
2023-11-24 23:46:43 +00:00
running on the host. This document used to recommend a workaround of telling
your IDE to listen on a different port (e.g., 9009) and setting
2020-09-09 12:27:11 +00:00
`XDEBUG_CONFIG=remote_port=9009` in your `.env` .
2019-11-13 15:34:03 +00:00
2023-11-24 23:46:43 +00:00
Xdebug 3.x now uses the `client_port` value, which defaults to 9003. This
2020-09-09 12:27:11 +00:00
should no longer conflict with local php-fpm installations, but you may need
to change the settings in your IDE or debugger.
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Linux desktop, host not found
2019-11-13 15:34:03 +00:00
2020-09-09 12:27:11 +00:00
The image uses `host.docker.internal` as the `client_host` value which
should allow Xdebug work for Docker for Mac/Windows.
2021-01-29 18:32:01 +00:00
On Linux, you need to create a `docker-compose.override.yml` file with the following
contents:
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
```yaml
2021-01-29 18:32:01 +00:00
services:
mediawiki:
extra_hosts:
- "host.docker.internal:host-gateway"
```
2020-09-09 12:27:11 +00:00
With the latest version of Docker on Linux hosts, this _should_ work
transparently as long as you're using the recommended
2023-11-24 23:46:43 +00:00
`docker-compose.override.yml` . If it doesn't, first check `docker version` to
2022-09-06 10:27:49 +00:00
make sure you're running Docker 20.10.2 or above, and `docker compose version`
2020-09-09 12:27:11 +00:00
to make sure it's 1.27.4 or above.
If Xdebug still doesn't work, try specifying the hostname or IP address of your
2023-11-24 23:46:43 +00:00
host. The IP address works more reliably. You can obtain it by running e.g.
2020-09-09 12:27:11 +00:00
`ip -4 addr show docker0` and copying the IP address into the config in `.env` ,
like `XDEBUG_CONFIG=remote_host=172.17.0.1`
2019-11-13 15:34:03 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### Generating logs
2019-11-13 15:34:03 +00:00
2020-09-09 12:27:11 +00:00
Switching on the remote log for Xdebug comes at a performance cost so only
2020-03-04 21:15:31 +00:00
use it while troubleshooting. You can enable it like so: `XDEBUG_CONFIG=remote_log=/tmp/xdebug.log`
2020-09-09 12:27:11 +00:00
2022-09-06 10:27:49 +00:00
### "(Permission Denied)" errors on running docker compose
2021-09-09 12:34:15 +00:00
See if you're able to run any docker commands to start with. Try running
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
`docker container ls` , which should also throw a permission error. If not,
2021-09-09 12:34:15 +00:00
go through the following steps to get access to the socket that the docker
client uses to talk to the daemon.
`sudo usermod -aG docker $USER`
2023-11-24 23:46:43 +00:00
And then `relogin` (or `newgrp docker` ) to re-login with the new group membership.
2021-09-09 12:34:15 +00:00
docs: Various DEVELOPERS.md improvements about MediaWiki-Docker
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
2021-09-11 18:00:00 +00:00
### "(Cannot access the database: Unknown error (localhost))"
2020-09-09 12:27:11 +00:00
The environment's working directory has recently changed to `/var/www/html/w` .
Reconfigure this in your `LocalSettings.php` by ensuring that the following
values are set correctly:
```php
$wgScriptPath = '/w';
$wgSQLiteDataDir = "/var/www/html/w/cache/sqlite";
```
2022-09-28 22:02:55 +00:00
### Windows users, "(Cannot access the database: No database connection (unknown))"
The permissions with the `cache/sqlite` directory have to be set manually on Windows:
2023-11-24 23:46:43 +00:00
2022-09-28 22:02:55 +00:00
```sh
docker compose exec mediawiki chmod -R o+rwx cache/sqlite
```
2024-05-04 08:42:21 +00:00
### Linux users, "(Cannot access the database: No database connection (localhost))"
Make sure you have the `MW_DOCKER_UID` and `MW_DOCKER_GID` set in your `.env` file (instructions above).
