Freephile Wiki

Using docker-compose-ci: Difference between revisions

Browse history interactively
Newer edit →
VisualWikitext
initial write-up
 
No edit summary
Line 1: Line 1:
These notes need to be incorporated with [[Automated deployment of MediaWiki]] and also [[PHPUnit/VSCode]]
These notes supplement [[Automated deployment of MediaWiki]] and also [[PHPUnit/VSCode]]


I added docker-compose-ci to the CrawlerProtection extension, and here is how to do it.
I added '''docker-compose-ci''' to the CrawlerProtection extension, and here is how to do it.


# create a Makefile
Initial setup
# create an .env file
 
# create a docker-compose-override.yml file in the 'build' directory
# create a <code>Makefile</code> in the project root
# create an .<code>env</code> file in the project root
# create a <code>docker-compose-override.yml</code> file '''in the 'build' directory'''
Fine-tuning
 
# add 'scripts' to composer.json
# add a .phpcs.xml
 
The neccessary files are shown below.
 
== Results ==
Bottom line up front: After this is setup, you can effortlessly test and check your code from your laptop/workstation before even making a commit, much less a pull request. You can avoid the work of creating GitHub Actions on your repo fork - which you can still do as an intermediary quality filter.
# From your laptop/workstation (host)
make bash
# Inside container:
composer phpcs      # Check code style
composer phpcbf     # Fix code style
composer phpunit    # Run tests
composer test       # Run phpcs + phpunit


== Makefile ==
== Makefile ==
'''do not''' specify COMPOSER_EXT=false or NODE_JS=false  Any value will cause that code branch to run, potentially causing a build failure.  
'''do not''' specify COMPOSER_EXT=false or NODE_JS=false  ''Any'' value will cause that code branch to run, potentially causing a build failure.  


<syntaxhighlight lang="makefile" line="1">
<syntaxhighlight lang="makefile" line="1">
Line 53: Line 72:
# NODE_JS=true  # Uncomment to enable Node.js and "npm install"
# NODE_JS=true  # Uncomment to enable Node.js and "npm install"
</syntaxhighlight>
</syntaxhighlight>
== docker-compose-override.yml ==
This file is critical to making life easier. Without it, you would have to resort to hacks like connecting VSCode to the container using remote explorer, configuring git for 'root' and adding roots .ssh key to your github repo. That's a lot of wasted effort when you can simply mount the host directory into the container and edit/commit using VSCode as usual.<syntaxhighlight lang="yaml">
services:
  wiki:
    volumes:
      # Mount your local extension directory into the container
      # Changes in container will reflect on host and vice versa
      - ../:/var/www/html/extensions/CrawlerProtection
    ports:
      # Optional: expose wiki on localhost:8080
      - "8080:8080"
</syntaxhighlight>
== Beautiful Code ==
'''[[Beautify|Using code beautifier]]''' to enforce MediaWiki coding standards.
If you haven't yet installed MediaWiki in the container, all the code will be there, but there will not be any <code>LocalSettings.php</code> file, and some tools won't work like they would on an installed wiki.
You can either <code>cd /var/www/html</code> and issue <code>phpcbf</code> commands directly rather than through the 'scripts' definition of MediaWiki's composer.json - which defines e.g. <code>composer fix</code> instead.
=== Direct usage ===
<code>./vendor/bin/phpcbf -d memory_limit=512M --standard=MediaWiki --ignore=*/build/*,*/vendor/* /var/www/html/extensions/CrawlerProtection/</code>
Or, you can create a <code>.phpcs.xml</code> configuration file for <code>phpcbf</code> that points to the vendored sniffs plus modify the extension's <code>composer.json</code> file to include a 'scripts' stanza that also points to MediaWiki's vendored binaries.
With the .phpcs.xml in place, you point to that as the 'standard' in your 'scripts' configuration, or on the command-line.
=== Fully-Configured usage ===
<code>composer phpcbf</code>
'''In the Docker container:'''
* Extension is at <code>/var/www/html/extensions/CrawlerProtection/</code>
* MediaWiki vendor is at <code>/var/www/html/vendor/</code>
* So <code>../../vendor/bin/phpcs</code> resolves correctly
'''In GitHub Actions:'''
* Extension is at <code>$GITHUB_WORKSPACE/extensions/CrawlerProtection/</code>
* MediaWiki vendor is at <code>$GITHUB_WORKSPACE/vendor/</code>
* Same <code>../../vendor/bin/phpcs</code> path works
'''Testing:'''
With everything in place, we should be able to <code>make bash</code> to get a command line in the container, and <code>composer phpcs</code> or <code>composer phpcbf</code> to run the tools.  Plus, fixes in the container can be viewed/edited/committed from VSCode on the host thanks to the <code>docker-compose-override.yml</code> filesystem mounts.
=== .phpcs.xml ===
<syntaxhighlight lang="xml" line="1">
<?xml version="1.0"?>
<ruleset name="CrawlerProtection">
<description>MediaWiki coding standards for CrawlerProtection extension</description>
<rule ref="../../vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
</rule>
<!-- Paths to check -->
<file>.</file>
<!-- Paths to ignore -->
<exclude-pattern>*/build/*</exclude-pattern>
<exclude-pattern>*/vendor/*</exclude-pattern>
<exclude-pattern>*/node_modules/*</exclude-pattern>
<exclude-pattern>*.phan/*</exclude-pattern>
<exclude-pattern>*/tests/phpunit/stubs.php</exclude-pattern>
<exclude-pattern>*/tests/phpunit/namespaced-stubs.php</exclude-pattern>
<!-- Show progress -->
<arg name="colors"/>
<arg name="encoding" value="UTF-8"/>
<arg name="extensions" value="php"/>
<arg value="sp"/>
<!-- Memory limit -->
<ini name="memory_limit" value="512M"/>
</ruleset>
</syntaxhighlight>
=== scripts ===
Here is the section of code to add to your Extension's <code>composer.json</code> to act like MediaWiki core for [[Continuous Integration]]<syntaxhighlight lang="json" line="1">
    "scripts": {
        "test": [
            "@phpcs",
            "@phpunit"
        ],
        "phpcs": "../../vendor/bin/phpcs -sp --standard=.phpcs.xml",
        "phpcbf": "../../vendor/bin/phpcbf --standard=.phpcs.xml",
        "phpunit": "../../vendor/bin/phpunit tests/phpunit"
    }
</syntaxhighlight>
{{References}}
Retrieved from "https://wiki.freephile.org/wiki/Using_docker-compose-ci"