Using docker-compose-ci: Difference between revisions

(2 intermediate revisions by the same user not shown)

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 the '''Gesinn IT''' [https://github.com/gesinn-it-pub/docker-compose-ci docker compose CI] system 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 ==

'''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.

Line 53:

Line 72:

# NODE_JS=true # Uncomment to enable Node.js and "npm install"

</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 ===

This is kinda long and difficult.

<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>

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 ===

<?xml version="1.0"?>

<description>MediaWiki coding standards for CrawlerProtection extension</description>

</rule>

<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>

</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": "php ../../tests/phpunit/phpunit.php tests/phpunit/"

},

"config": {

"allow-plugins": {

"dealerdirect/phpcodesniffer-composer-installer": true

}

</syntaxhighlight>Note about path resolution: snippet shows 'vendor/bin' as the path which is the local tool installed by 'composer install' from the extension directory in the container. This is available because we added require-dev libraries.

'''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 if using core's tools

'''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

@@ 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 the '''Gesinn IT''' [https://github.com/gesinn-it-pub/docker-compose-ci docker compose CI] system 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 ==
-'''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">
@@ Line 53: / Line 72: @@
 # NODE_JS=true  # Uncomment to enable Node.js and "npm install"
 </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 ===
+This is kinda long and difficult.
+<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>
+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>
+	<!-- test stub files intentionally have multiple classes in one file -->
+	<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": "php ../../tests/phpunit/phpunit.php tests/phpunit/"
+    },
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    }
+</syntaxhighlight>Note about path resolution: snippet shows 'vendor/bin' as the path which is the local tool installed by 'composer install' from the extension directory in the container. This is available because we added require-dev libraries.
+'''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 if using core's tools
+'''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
+{{References}}