docs: contributing on Windows (#2222)

Signed-off-by: Kévin Dunglas <kevin@dunglas.fr>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: dunglas

.github/workflows/windows.yaml

@@ -217,7 +217,7 @@ jobs:
           "opcache.enable=0`r`nopcache.enable_cli=0" | Out-File php.ini
           $env:PHPRC = Get-Location
 
-          go test ./...
+          go test -race ./...
           cd caddy
-          go test ./...
+          go test -race ./...
         working-directory: ${{ github.workspace }}\frankenphp

CONTRIBUTING.md

@@ -17,7 +17,7 @@ The image contains the usual development tools (Go, GDB, Valgrind, Neovim...) an
 - additional configuration files: `/etc/frankenphp/php.d/*.ini`
 - php extensions: `/usr/lib/frankenphp/modules/`
 
-If your Docker version is lower than 23.0, the build will fail due to dockerignore [pattern issue](https://github.com/moby/moby/pull/42676). Add directories to `.dockerignore`.
+If your Docker version is lower than 23.0, the build will fail due to dockerignore [pattern issue](https://github.com/moby/moby/pull/42676). Add directories to `.dockerignore`:
 
 ```patch
  !testdata/*.php
@@ -30,14 +30,14 @@ If your Docker version is lower than 23.0, the build will fail due to dockerigno
 
 [Follow the instructions to compile from sources](https://frankenphp.dev/docs/compile/) and pass the `--debug` configuration flag.
 
-## Running the test suite
+## Running the Test Suite
 
 ```console
-export CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
+export CGO_CFLAGS=-O0 -g $(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
 go test -race -v ./...
 ```
 
-## Caddy module
+## Caddy Module
 
 Build Caddy with the FrankenPHP Caddy module:
 
@@ -57,13 +57,13 @@ cd testdata/
 The server is listening on `127.0.0.1:80`:
 
 > [!NOTE]
-> if you are using Docker, you will have to either bind container port 80 or execute from inside the container
+> If you are using Docker, you will have to either bind container port 80 or execute from inside the container
 
 ```console
 curl -vk http://127.0.0.1/phpinfo.php
 ```
 
-## Minimal test server
+## Minimal Test Server
 
 Build the minimal test server:
 
@@ -86,9 +86,76 @@ The server is listening on `127.0.0.1:8080`:
 curl -v http://127.0.0.1:8080/phpinfo.php
 ```
 
+## Windows Development
+
+1. Configure Git to always use `lf` line endings
+
+    ```powershell
+    git config --global core.autocrlf false
+    git config --global core.eol lf
+    ```
+
+2. Install Visual Studio, Git, and Go:
+
+    ```powershell
+    winget install -e --id Microsoft.VisualStudio.2022.Community --override "--passive --wait --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended"
+    winget install -e --id GoLang.Go
+    winget install -e --id Git.Git
+    ```
+
+3. Install vcpkg:
+
+    ```powershell
+    cd C:\
+    git clone https://github.com/microsoft/vcpkg
+    .\vcpkg\bootstrap-vcpkg.bat
+    ```
+
+4. [Download the latest version of the watcher library for Windows](https://github.com/e-dant/watcher/releases) and extract it to a directory named `C:\watcher`
+5. [Download the latest **Thread Safe** version of PHP and of the PHP SDK for Windows](https://windows.php.net/download/), extract them in directories named `C:\php` and `C:\php-devel`
+6. Clone the FrankenPHP Git repository:
+
+    ```powershell
+    git clone https://github.com/php/frankenphp C:\frankenphp
+    cd C:\frankenphp
+    ```
+
+7. Install the dependencies:
+
+    ```powershell
+    C:\vcpkg\vcpkg.exe install
+    ```
+
+8. Configure the needed environment variables (PowerShell):
+
+    ```powershell
+    $env:PATH += ';C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\bin'
+    $env:CC = 'clang'
+    $env:CXX = 'clang++'
+    $env:CGO_CFLAGS = "-O0 -g -IC:\frankenphp\vcpkg_installed\x64-windows\include -IC:\watcher -IC:\php-devel\include -IC:\php-devel\include\main -IC:\php-devel\include\TSRM -IC:\php-devel\include\Zend -IC:\php-devel\include\ext"
+    $env:CGO_LDFLAGS = '-LC:\frankenphp\vcpkg_installed\x64-windows\lib -lbrotlienc -LC:\watcher -llibwatcher-c -LC:\php -LC:\php-devel\lib -lphp8ts -lphp8embed'
+    ```
+
+9. Run the tests:
+
+    ```powershell
+    go test -race -ldflags '-extldflags="-fuse-ld=lld"' ./...
+    cd caddy
+    go test -race -ldflags '-extldflags="-fuse-ld=lld"' -tags nobadger,nomysql,nopgx ./...
+    cd ..
+    ```
+
+10. Build the binary:
+
+    ```powershell
+    cd caddy/frankenphp
+    go build -ldflags '-extldflags="-fuse-ld=lld"' -tags nobadger,nomysql,nopgx
+    cd ../..
+    ```
+
 ## Building Docker Images Locally
 
-Print bake plan:
+Print Bake plan:
 
 ```console
 docker buildx bake -f docker-bake.hcl --print
@@ -125,7 +192,7 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
    docker cp $(docker create --name static-builder-musl dunglas/frankenphp:static-builder-musl):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
    ```
 
-2. Replace your current version of `frankenphp` by the debug FrankenPHP executable
+2. Replace your current version of `frankenphp` with the debug FrankenPHP executable
 3. Start FrankenPHP as usual (alternatively, you can directly start FrankenPHP with GDB: `gdb --args frankenphp run`)
 4. Attach to the process with GDB:
 
@@ -155,7 +222,7 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 
    ```patch
        - name: Set CGO flags
-         run: echo "CGO_CFLAGS=$(php-config --includes)" >> "$GITHUB_ENV"
+         run: echo "CGO_CFLAGS=-O0 -g $(php-config --includes)" >> "$GITHUB_ENV"
    +   - run: |
    +       sudo apt install gdb
    +       mkdir -p /home/runner/.config/gdb/
@@ -207,14 +274,14 @@ strace -e 'trace=!futex,epoll_ctl,epoll_pwait,tgkill,rt_sigreturn' -p 1
 
 ## Translating the Documentation
 
-To translate the documentation and the site in a new language,
+To translate the documentation and the site into a new language,
 follow these steps:
 
 1. Create a new directory named with the language's 2-character ISO code in this repository's `docs/` directory
 2. Copy all the `.md` files in the root of the `docs/` directory into the new directory (always use the English version as source for translation, as it's always up to date)
 3. Copy the `README.md` and `CONTRIBUTING.md` files from the root directory to the new directory
 4. Translate the content of the files, but don't change the filenames, also don't translate strings starting with `> [!` (it's special markup for GitHub)
 5. Create a Pull Request with the translations
-6. In the [site repository](https://github.com/dunglas/frankenphp-website/tree/main), copy and translate the translation files in the `content/`, `data/` and `i18n/` directories
+6. In the [site repository](https://github.com/dunglas/frankenphp-website/tree/main), copy and translate the translation files in the `content/`, `data/`, and `i18n/` directories
 7. Translate the values in the created YAML file
 8. Open a Pull Request on the site repository