docs: Move the gitlab wiki and other docs to the docs/ directory

Let's try to consolidate our documentation in doc/ in the repo. This
includes some documentation from README.md, the HACKING.md coding style
and the gitlab wiki.

The README.md file now links to all top-level topics (i.e. not reachable
via other topics).

This also includes a few small changes to make things more consistent.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3465>

README.md

@@ -26,10 +26,17 @@ debugging purposes.
 
 To contribute, open merge requests at https://gitlab.gnome.org/GNOME/mutter.
 
-It can be useful to look at the documentation available at the
+It can be useful to look at the documentation and API references below first.
-[Wiki](https://gitlab.gnome.org/GNOME/mutter/-/wikis/home).
 
-The API documentation is available at:
+## Documentation
+
+- [Coding style and conventions](doc/coding-style.md)
+- [Git conventions](doc/git-conventions.md)
+- [Code overview](doc/code-overview.md)
+- [Debugging](doc/debugging.md)
+- [Monitor configuration](doc/monitor-configuration.md)
+
+## API Reference
 
 - Meta: <https://gnome.pages.gitlab.gnome.org/mutter/meta/>
 - Clutter: <https://gnome.pages.gitlab.gnome.org/mutter/clutter/>
@@ -38,71 +45,6 @@ The API documentation is available at:
 - CoglPango: <https://gnome.pages.gitlab.gnome.org/mutter/cogl-pango/>
 - Mtk: <https://gnome.pages.gitlab.gnome.org/mutter/mtk/>
 
-## Coding style and conventions
-
-See [HACKING.md](./HACKING.md).
-
-## Git messages
-
-Commit messages should follow the [GNOME commit message
-guidelines](https://wiki.gnome.org/Git/CommitMessages). We require an URL
-to either an issue or a merge request in each commit. Try to always prefix
-commit subjects with a relevant topic, such as `compositor:` or
-`clutter/actor:`, and it's always better to write too much in the commit
-message body than too little.
-
-If a commit fixes an issue and that issue should be closed, add URL to it in
-the bottom of the commit message and prefix with `Closes:`.
-
-Do not add any `Part-of:` line, as that will be handled automatically when
-merging.
-
-### The Fixes tag
-
-If a commit fixes a regression caused by a particular commit, it can be marked
-with the `Fixes:` tag. To produce such a tag, use
-
-```
-git show -s --pretty='format:Fixes: %h (\"%s\")' <COMMIT>
-```
-
-or create an alias
-
-```
-git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
-```
-
-and then use
-
-```
-git fixes <COMMIT>
-```
-
-### Example
-
-```
-compositor: Also consider dark matter when calculating paint volume
-
-Ignoring dark matter when calculating the paint volume missed the case where
-compositing happens in complete vacuum.
-
-Fixes: 123abc123ab ("compositor: Calculate paint volume ourselves")
-Closes: https://gitlab.gnome.org/GNOME/mutter/-/issues/1234
-```
-
-## Default branch
-
-The default development branch is `main`. If you still have a local
-checkout under the old name, use:
-```sh
-git checkout master
-git branch -m master main
-git fetch
-git branch --unset-upstream
-git branch -u origin/main
-git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
-```
-
 ## License
 
 Mutter is distributed under the terms of the GNU General Public License,

doc/code-overview.md

@@ -0,0 +1,25 @@
+# Code Overview
+
+Mutter consists of four relatively distinguished and isolated parts.
+
+## Cogl
+
+Hardware acceleration pipeline abstraction layer. Handles things like allocating framebuffer, allocating, importing and drawing textures, internally using OpenGL. Originally a fork of [the Cogl project](https://gitlab.gnome.org/GNOME/cogl).
+
+## Clutter
+
+Compositing toolkit, containing an actor and render node based scene graph, and has features such as input event routing, transformation and animation. Handles compositing, both Wayland surfaces, X11 windows, and is the basis of the UI toolkit implemented by [GNOME Shell](https://gitlab.gnome.org/GNOME/gnome-shell). Originally a fork of [the Clutter project](https://gitlab.gnome.org/GNOME/clutter).
+
+* [Frame Scheduling](frame-scheduling.md)
+
+## Mtk
+
+The Meta Toolkit containing utilities shared by other parts of mutter.
+
+## Mutter
+
+The display server and window manager library. Contains a X11 window manager and compositing manager implementation, as well as a Wayland display server implementation.
+
+* [Compositor stage and hardware relationships](mutter-relationships.md)
+* [Window constraints](how-constraints-works.txt)
+* [How to get focus right](how-to-get-focus-right.txt)

doc/debugging.md

@@ -0,0 +1,92 @@
+# Debugging
+
+## Nested D-Bus session
+
+### Installing
+
+Download and place [dbus-session.sh](uploads/a209c8f1fe6b51df669b58bab1300199/dbus-session.sh) in `~/.local/bin/` and make it executable.
+
+### Using
+
+To create a nested D-Bus user session, run
+
+```sh
+dbus-session.sh -n
+```
+
+This will create a D-Bus session, and attach to it.
+
+To attach to the same session from another terminal, run
+
+```sh
+dbus-session.sh -x
+```
+
+## Nested mutter or gnome-shell
+
+To run a nested mutter or gnome-shell instance, i.e. when you are presented with a floating window running mutter or gnome-shell, first enter a [nested D-Bus session](#nested-d-bus-session), then pass `--nested` to either gnome-shell or mutter. E.g.
+
+```sh
+mutter --nested
+```
+
+## Headless GNOME Shell and GNOME Remote Desktop
+
+First create [nested D-Bus session](#nested-d-bus-session). In this, run gnome-shell in headless mode with a virtual monitor. E.g.
+
+```sh
+[jonas@localhost gnome-shell]$ dbus-session.sh -n
+[ D-Bus 60ff ][jonas@localhost gnome-shell]$ gnome-shell --headless --virtual-monitor 1280x720
+```
+
+```sh
+[jonas@localhost gnome-remote-desktop]$ dbus-session.sh -x
+[ D-Bus 60ff ][jonas@localhost gnome-remote-desktop]$ ./build/src/gnome-remote-desktop-daemon
+```
+
+
+
+## Reproducing CI test failures locally
+
+1. Create a podman that can run gdb locally using the same image used in CI. The example below uses the tag `x86_64-2022-01-20` but this will depend on the image used by the failed CI job. The Fedora version may also differ.
+
+    ```sh
+    podman pull registry.gitlab.gnome.org/gnome/mutter/fedora/35:x86_64-2022-01-20
+    podman run -t -i --cap-add=SYS_PTRACE registry.gitlab.gnome.org/gnome/mutter/fedora/35:x86_64-2022-01-20 bash -l
+    ```
+
+2. Clone, build and install mutter inside the container
+
+    ```sh
+    git clone https://gitlab.gnome.org/[your-user]/mutter.git -b [merge-request-branch]
+    cd mutter
+    meson build
+    ninja -C build install
+    ```
+
+3. Install debug utilities
+
+    ```sh
+    dnf install -y gdb
+    ```
+
+4. Replicate a environment and run the test inside gdb. What you need here depends on the test that needs investigation. In the simplest case, the following is enough:
+
+    ```sh
+    export XDG_RUNTIME_DIR=$PWD/runtime-dir
+    mkdir -p $XDG_RUNTIME_DIR
+    ./src/tests/meta-dbus-runner.py xvfb-run meson test -C build --setup plain --gdb failing-test-case
+    ```
+
+    The need for `xvfb-run` depends on whether the test case uses the nested backend or the headless backend.
+
+    If it involves screen casting, it becomes a bit more complicated:
+
+    ```sh
+    export XDG_RUNTIME_DIR=$PWD/runtime-dir
+    mkdir -p $XDG_RUNTIME_DIR
+    ./src/tests/meta-dbus-runner.py bash -l
+    pipewire&
+    wireplumber&
+    meson test -C build --setup plain --gdb failing-test-case
+    ```

doc/frame-scheduling.md

@@ -0,0 +1,14 @@
+# Frame scheduling
+
+`ClutterFrameClock` state diagram.
+
+```mermaid
+stateDiagram
+    Init --> Scheduled : schedule update() -> now
+    Idle --> Scheduled : schedule update() -> given presentation time
+    Scheduled --> Dispatching : target time hit
+    Dispatching --> PendingPresented : queued page flip
+    Dispatching --> Idle : no queued page flip
+    PendingPresented --> Scheduled : page flipped, if recent schedule update
+    PendingPresented --> Idle : page flipped
+```

doc/git-conventions.md

@@ -0,0 +1,49 @@
+# Git conventions
+
+## Commit Messages
+
+Commit messages should follow the [GNOME commit message
+guidelines](https://wiki.gnome.org/Git/CommitMessages). We require an URL
+to either an issue or a merge request in each commit. Try to always prefix
+commit subjects with a relevant topic, such as `compositor:` or
+`clutter/actor:`, and it's always better to write too much in the commit
+message body than too little.
+
+If a commit fixes an issue and that issue should be closed, add URL to it in
+the bottom of the commit message and prefix with `Closes:`.
+
+Do not add any `Part-of:` line, as that will be handled automatically when
+merging.
+
+### The Fixes tag
+
+If a commit fixes a regression caused by a particular commit, it can be marked
+with the `Fixes:` tag. To produce such a tag, use
+
+```
+git show -s --pretty='format:Fixes: %h (\"%s\")' <COMMIT>
+```
+
+or create an alias
+
+```
+git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
+```
+
+and then use
+
+```
+git fixes <COMMIT>
+```
+
+### Example
+
+```
+compositor: Also consider dark matter when calculating paint volume
+
+Ignoring dark matter when calculating the paint volume missed the case where
+compositing happens in complete vacuum.
+
+Fixes: 123abc123ab ("compositor: Calculate paint volume ourselves")
+Closes: https://gitlab.gnome.org/GNOME/mutter/-/issues/1234
+```

doc/monitor-configuration.md

@@ -1,8 +1,6 @@
-Monitor configuration
+# Monitor configuration
-=====================
 
-File locations
+## File locations
---------------
 
 Monitor configurations are stored as XML files called `monitors.xml` on the file
 system. There are two types of locations for the XML file: the system level and
@@ -16,8 +14,7 @@ The directory for the user level configuration is defined in accordance to the
 $XDG_CONFIG_HOME environment variable defined in the XDG Base Directory
 Specification. The default is `~/.config/monitors.xml`
 
-File contents
+## File contents
--------------
 
 A configuration file consists of an XML document with the root element
 `<monitors version="2">`. In this document multiple configurations are stored as
@@ -28,8 +25,7 @@ Each configuration corresponds to a specific hardware setup, where a given set
 of monitors are connected to the computer. There can only be one configuration
 per hardware setup.
 
-Writing configuration
+## Writing configuration
----------------------
 
 Monitor configurations are managed by Mutter via the Display panel in Settings,
 which uses a D-Bus API to communicate with Mutter. Each time a new configuration
@@ -39,8 +35,7 @@ updated content.
 Previously defined monitor configurations for hardware state other than the
 current are left intact.
 
-Configuration policy
+## Configuration policy
---------------------
 
 The monitor configuration policy determines how Mutter configures monitors. This
 can mean for example in what order configuration files should be preferred, or

doc/mutter-relationships.md

@@ -0,0 +1,135 @@
+# Compositor stage and hardware relationships
+
+## Brief description of components
+
+ - `MetaLogicalMonitor` is one monitor or more monitor occupying the same region of the compositor space. E.g. when mirroring two monitors, both belong to the same logical monitor.
+ - `MetaMonitor` is a single physical monitor, but it can sometimes consist of more than one separate panel (for instance, 5K tiled monitors which literally require 2 cables due to lack of bandwidth)
+ - `MetaOuptut` is a connector e.g. a DisplayPort connector or HDMI connector.
+ - `MetaCrtc` represents a component on the display hardware that channels video memory to connectors.
+
+## Entity relationship diagram
+
+```mermaid
+erDiagram
+  MetaBackend ||--|| MetaMonitorManager : owns
+  MetaBackend ||--|{ MetaGpu : owns
+  MetaBackend ||--|| ClutterStage : owns
+  MetaGpu ||--|{ MetaCrtc : owns
+  MetaGpu ||--|{ MetaOutput : owns
+  MetaCrtc |o..o{ MetaOutput : assigned
+  MetaBackend ||--|{ MetaVirtualMonitor : owns
+  MetaVirtualMonitor ||--|| MetaCrtc : owns
+  MetaVirtualMonitor ||--|| MetaOutput : owns
+  MetaMonitorManager ||--|{ MetaMonitor : owns
+  MetaMonitorManager ||--|{ MetaLogicalMonitor : owns
+  MetaLogicalMonitor ||..|{ MetaMonitor : has
+  MetaMonitor ||..|{ MetaOutput : has
+  ClutterStage ||--|{ ClutterStageView : has
+  ClutterStageView ||..|| MetaCrtc : corresponds
+  ClutterStageView ||--|| ClutterFrameClock : owns
+  ClutterStageView ||..|| MetaLogicalMonitor : derive-scale
+```
+
+## Class diagrams
+
+`MetaBackend`, `MetaGpu` and `MetaMonitorManager` class diagrams.
+
+```mermaid
+classDiagram
+    MetaBackend <-- MetaBackendNative
+    MetaBackend <-- MetaBackendX11
+    class MetaBackend{
+      MetaMonitorManager monitor_manager
+      List~MetaGpu~ gpus
+    }
+    MetaGpu <-- MetaGpuKms
+    MetaGpu <-- MetaGpuXrandr
+    class MetaGpu{
+      List~MetaOutput~
+      List~MetaCrtc~
+    }
+    MetaMonitorManager <-- MetaMonitorManagerNative
+    MetaMonitorManager <-- MetaMonitorManagerXrandr
+    class MetaMonitorManager{
+      List~MetaMonitor~ monitors
+      List~MetaLogicalMonitor~ logical_monitors
+    }
+```
+
+`MetaLogicalMonitor`, `MetaMonitor`, `MetaOutput` and `MetaCrtc` class diagrams.
+
+```mermaid
+classDiagram
+    MetaLogicalMonitor
+    class MetaLogicalMonitor{
+      List~MetaMonitor~
+    }
+    MetaMonitor <-- MetaMonitorNormal
+    MetaMonitor <-- MetaMonitorTiled
+    class MetaMonitorNormal{
+      MetaOutput output
+    }
+    class MetaMonitorTiled{
+      List~MetaOutput~ output
+    }
+    MetaOutput <-- MetaOutputNative
+    MetaOutputNative <-- MetaOutputKms
+    MetaOutputNative <-- MetaOutputVirtual
+    MetaOutput <-- MetaOutputXrandr
+    MetaCrtc <-- MetaCrtcNative
+    MetaCrtcNative <-- MetaCrtcKms
+    MetaCrtcNative <-- MetaCrtcVirtual
+    MetaCrtc <-- MetarCrtcXrandr
+```
+
+`ClutterStage` and `ClutterStageView` class diagram when using the Wayland session.
+
+```mermaid
+classDiagram
+    class ClutterStage{
+      List~ClutterStageView~
+    }
+    class ClutterStageView{
+      MetaCrtc crtc
+    }
+```
+
+`MetaKms` class diagram.
+
+```mermaid
+classDiagram
+    class MetaKms{
+      List~MetaKmsDevice~ devices
+    }
+    class MetaKmsDevice{
+      List~MetaKmsConnector~
+      List~MetaKmsCrtc~
+      List~MetaKmsPlane~
+      MetaKmsImplDevice impl_device
+    }
+    MetaKms "many" --> MetaKmsDevice : Owns
+    MetaKmsDevice --> MetaKmsImplDevice : Owns
+    MetaKmsImplDevice <-- MetaKmsImplDeviceAtomic
+    MetaKmsImplDevice <-- MetaKmsImplDeviceSimple
+```
+
+## Native backend and mode setting
+
+ * `MetaGpuKms`, `MetaCrtcKms` and `MetaOutputKms` are used for configuration.
+ * `MetaKmsDevice`, `MetaKmsCrtc`, `MetaKmsConnector` and `MetaKmsPlane` are abstractions on top of kernel mode setting concepts.
+
+```mermaid
+erDiagram
+  MetaBackendNative ||--|{ MetaGpuKms : owns
+  MetaBackendNative ||--|| MetaKms : owns
+  MetaKms ||--|{ MetaKmsDevice : owns
+  MetaKmsDevice ||--|{ MetaKmsCrtc : owns
+  MetaKmsDevice ||--|{ MetaKmsConnector : owns
+  MetaKmsDevice ||--|{ MetaKmsPlane : owns
+  MetaGpuKms ||--|{ MetaCrtcKms : owns
+  MetaGpuKms ||--|{ MetaOutputKms : owns
+  MetaCrtcKms |o..o{ MetaOutputKms : assigned
+  MetaGpuKms |o..o| MetaKmsDevice : associated
+  MetaCrtcKms |o..o| MetaKmsCrtc : associated
+  MetaOutputKms |o..o| MetaKmsConnector : associated
+```

tools/uncrustify.cfg

@@ -1,6 +1,6 @@
 # Run `uncrustify --show-config` to see documentation for these options.
 #
-# See also: https://gitlab.gnome.org/GNOME/mutter/-/blob/master/HACKING.md
+# See also: https://gitlab.gnome.org/GNOME/mutter/-/blob/main/doc/coding-style.md
 
 #################################################################################
 # CHANGES