Add more documentation for WebKitGTK and WPE WebKit

Author: mcatanzaro

docs/Build & Debug/BuildOptions.md

@@ -64,8 +64,6 @@ Tools/Scripts/update-webkitgtk-libs
 Tools/Scripts/build-webkit --gtk --debug
 ```
 
-For more information on building WebKitGTK, see the [wiki page](https://trac.webkit.org/wiki/BuildingGtk).
-
 ## Building the WPE Port
 
 For production builds:

docs/Ports/Introduction.md

@@ -0,0 +1,13 @@
+# What Are WebKit Ports?
+
+WebKit has been ported to various platforms and operating systems. The platform-specific code for each port is maintained by different teams that collaborate on the cross-platform code. The code for upstream ports is maintained directly in the [WebKit GitHub repository](https://github.com/WebKit/webkit). The following upstream ports are available:
+
+ * Apple maintains the WebKit ports for macOS, iOS, and other Apple operating systems.
+ * [Igalia](https://www.igalia.com) maintains two WebKit ports for Linux, [WebKitGTK](https://webkitgtk.org) and [WPE WebKit](https://wpewebkit.org).
+ * Sony maintains the WebKit port for PlayStation.
+ * The Windows port facilitates development and testing of WebKit using Windows.
+ * The JSCOnly port facilitates development and testing of JavaScriptCore without the rest of WebKit.
+
+There are also several downstream ports of WebKit, which are maintained entirely separately. Because they are not developed upstream, downstream ports are based on different versions of WebKit. Some downstream ports may be [old and insecure](https://blogs.gnome.org/mcatanzaro/2022/11/04/stop-using-qtwebkit/).
+
+There are no cross-platform releases of WebKit. Each WebKit port is responsible for creating their own separate releases, if desired. The same applies for security advisories. Currently the ports maintained by Apple and Igalia have regular releases and security advisories, while other upstream ports do not.

docs/Ports/WebKitGTK and WPE WebKit/DependenciesPolicy.md

@@ -0,0 +1,23 @@
+# Dependencies Policy
+
+WebKitGTK's dependencies policy is simple:
+
+* We support each major Debian version until one year after the release of the next major version.
+* We support each Ubuntu LTS until one year after the release of the next Ubuntu LTS.
+
+During the support period, we intend for WebKit to remain buildable on these distributions using some system-provided compiler -- not necessarily the default system compiler -- and with the default system libstdc++. The purpose of this policy is to ensure distributions can provide updated versions of WebKit during the support period to ensure users receive security updates.
+
+For more information on compiler requirements, see [GCC Requirement](GCCRequirement.md).
+
+* ​[Debian Releases](https://www.debian.org/releases/)
+* [Debian Packages](https://www.debian.org/distrib/packages)
+* [Ubuntu Releases](https://wiki.ubuntu.com/Releases)
+* [Ubuntu Packages Search](https://packages.ubuntu.com/)
+
+| Operating System               | Release Date | WebKit Support End |
+|--------------------------------|--------------|--------------------|
+| Debian 10 (Buster)             | 2019-07-06   | 2022-08-14         |
+| Ubuntu 20.04 (Focal Fossa)     | 2020-04-23   | 2023-04-21         |
+| Debian 11 (Bullseye)	         | 2021-08-14   | 2024-06-10         |
+| Ubuntu 22.04 (Jammy Jellyfish) | 2022-04-21   | April 2025         |
+| Debian 12 (Bookworm)           | 2023-06-10   |                    |

docs/Ports/WebKitGTK and WPE WebKit/GCCRequirement.md

@@ -0,0 +1,7 @@
+# GCC Requirement
+
+WebKit is a complex C++ library that often requires relatively new versions of GCC to build. Older versions of GCC tend to have bugs that prevent code from compiling successfully, which tend to be fixed in newer versions of GCC, and which are often encountered in practice by WebKit developers. Apple also likes to be able to use new C++ features, which are often not present in older versions of GCC, relatively early.
+
+We are aware that Linux distributions and embedded systems vendors like to be able to compile everything with the same system build toolchain, which may be very old, so we have compromised with Apple to develop a [dependencies policy](DependenciesPolicy.md) that attempts to balance the interests of both WebKit distributors and developers. We intend to support some system compilers in the latest Ubuntu LTS and Debian stable releases until one year after the subsequent release, but, depending on the age of the release, this might be some version of Clang rather than GCC. We no longer provide any timeline as to how long a particular version of GCC may be supported, as this decision will be made by WebKit developers on a case-by-case basis. However, we will always support the version of libstdc++ available in these releases until one year after the subsequent release. Preserving compatibility with older standard library versions is necessary to allow updates on older systems, even if a newer compiler is used to build those updates. In general, you can expect a new standard library version to be supported by WebKit for approximately three to four years, in accordance with the dependencies policy.
+
+This policy means that WebKit may require a new version of GCC sooner than you might prefer. Because Apple does not use GCC to develop WebKit, and because of the relatively high number of compatibility issues caused by supporting GCC, we should be grateful that it is still possible to build WebKit with GCC at all. Unless you are able to upgrade your systems to newer GCCs on a regular basis, it is expected that your system GCC may not be new enough to build WebKit. We urge you to consider building with a different compiler if your system compiler is too old. Embedded systems vendors may choose to deploy WebKit in a container if updating the host's libstdc++ is undesirable. If you choose to stop building new versions of WebKit as a result of an increased GCC or libstdc++ version requirement, your users will be left vulnerable to numerous security vulnerabilities that are fixed in newer versions.

docs/Ports/WebKitGTK and WPE WebKit/ReleasesAndVersioning.md

@@ -0,0 +1,16 @@
+# Releases and Versioning
+
+WebKitGTK and WPE WebKit follow a 6-month development cycle and the releases for both ports are usually synced.
+
+Here is an overview of what the version numbers mean:
+
+* Version numbers follow the major.minor.patch numbering scheme.
+* Changes to the major version are very rare and signify considerable architectural changes.
+* The minor version number changes throughout the development cycle and it is possible to identify if a release is stable or not by looking at this number
+    * An even minor version number means the release is stable and ready for production.
+    * An odd minor version number means the release is a development (beta) release for testing or preview of new features.
+* The patch number is incremented for each bugfix release and is just an incremental number.
+
+There are two stable features releases every year (where the minor number is increased to an even number and the patch number is zero), typically in March and September. There may be any number of bugfix releases (where the patch number is increased).
+
+[Read more about the WPE WebKit release process and versioning scheme](https://wpewebkit.org/release/schedule/).

docs/Ports/WebKitGTK and WPE WebKit/SecurityUpdates.md

@@ -0,0 +1,45 @@
+# Security Updates
+
+Before reading this document, please also [learn about WebKit ports](../Introduction.md) and [WebKitGTK and WPE WebKit releases and versioning](ReleasesAndVersioning.md).
+
+## WebKitGTK and WPE WebKit Security Updates
+
+Developers actively backport security fixes from the WebKit main development branch into the latest stable release.
+
+Any stable release may contain security fixes. The concept of "stable release" is any release where the minor number is an even number. Developers periodically release security advisories detailing which security issues have been found and which releases were affected. Developers issue these security advisories shortly after creating a new stable release fixing the problem.
+
+Developers don't generally backport security fixes for older stable releases. **Security updates are only available for the latest stable release branch**, i.e. the latest branch with an even minor version number.
+
+For more information about the security advisories, see:
+
+* [WebKitGTK Security Advisories](https://webkitgtk.org/security.html)
+* [WPE WebKit Security Advisories](https://wpewebkit.org/security)
+
+## Recommended Practices
+
+These are the recommended practices for users that would like to incorporate security and privacy updates from WebKit into their app in a timely manner:
+
+* Use the latest stable version of WebKitGTK or WPE WebKit.
+    * Even if a specific stable release doesn't mention that it contains a security fix, it is still a very good idea to update.
+    * Stable releases may fix dangerous crashes or issues that may be not tagged as a security issue at the moment of the release.
+    * Updating to the latest stable versions of WebKitGTK and WPE WebKit is always recommended: it is the best way of ensuring you are running a safe version of WebKit.
+
+* Subscribe to the mailing lists to get notifications about new releases and security advisories.
+    * Security advisories are sent to the port mailing list, so it is recommended to subscribe to it:
+        * [WebKitGTK mailing list](https://lists.webkit.org/mailman/listinfo/webkit-gtk)
+        * [WPE WebKit mailing list](https://lists.webkit.org/mailman/listinfo/webkit-wpe)
+
+* Verify the tarballs of the releases.
+    * The release tarballs include checksums and are also signed with PGP signatures.
+    * After downloading the release, it is recommended to check the checksums or verify the PGP signature. Verifying the PGP signature is the best way to ensure your download was not compromised.
+    * See:
+        *  [Verifying WebKitGTK releases](https://webkitgtk.org/verifying.html)
+        *  [Verifying WPE WebKit releases](https://wpewebkit.org/release/verify)
+
+
+## Considerations When Applying Security Updates
+
+Some considerations to take into account when applying security updates:
+
+* The WebKitGTK and WPE WebKit API aims to be compatible between minor versions, so if the application was using an older minor version of WebKitGTK or WPE WebKit, it should also run with the newer version of WebKitGTK or WPE WebKit without issues. (Recompiling the application is not needed.)
+* The major version rarely changes, but if it does then you may need to check if the application code still builds and works fine with the new major version. In that case there should be a guide explaining how to port the code of the application.