[gnome-initial-setup/wip/wjt/update-contributing: 2/3] Rewrite CONTRIBUTING.md

[Marge Bot <marge-bot src gnome org>]

commit 89ad0984619f6b5a9f8e3dc7fa1ee82c96e0eb52
Author: Will Thompson <wjt endlessos org>
Date:   Fri Sep 23 09:58:52 2022 +0100

    Rewrite CONTRIBUTING.md
    
    This is rather out of date. Rewrite it, removing outright falsehoods.
    
    Part-of: <https://gitlab.gnome.org/GNOME/gnome-initial-setup/-/merge_requests/162>

 CONTRIBUTING.md | 85 +++++++++++++++++++++++++++++++--------------------------
 1 file changed, 46 insertions(+), 39 deletions(-)
---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ea78123c..bd3754d5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,65 +3,72 @@ Initial Setup
 
 The first time a new system is booted is a special situation. There is
 no user account yet, and a few basic setup steps need to be performed
-before it can be considered fully usable. The initial-setup mode is an
+before it can be considered fully usable. The initial setup mode is an
 attempt to solve these problems.
 
-When in initial-setup mode, gdm does not bring up the regular greeter
-for the login screen, but instead starts the gnome-initial-setup
-application in a special session. gnome-initial-setup offers a series
-of steps to
+When in initial setup mode, GDM does not bring up the regular greeter
+for the login screen, but instead starts the `gnome-initial-setup`
+application in a special session. `gnome-initial-setup` offers a series
+of steps to:
 
-1. Select your language
+1. Select a language
 2. Select a keyboard layout
-3. Accept any End User Licence Agreements
-4. Connect to the network
-5. Create a new user account
-6. Set the right location/timezone
+3. Connect to the network
+4. Adjust some privacy settings
+5. Set the right location/timezone
+6. Configure software sources
 7. Set up online accounts
+8. Create a new user account
+9. Configure parental controls
 
 In terms of the user experience, we want the initial setup to seamlessly
 switch to the regular user session. In particular, we don't want to
-make the user enter his credentials again on the login screen.
+make the user enter their credentials again on the login screen.
 
-We can't run the gnome-initial-setup application with the correct user,
-since the user account does not exist yet at that time. Therefore, gdm
-creates a temporary gnome-initial-setup user, and runs gnome-initial-setup
-as that user. When gdm-inital-setup is done, it then initiates an
-autologin for the newly created user account to switch to the 'real'
-session. gdm removes the temporary gnome-initial-setup user before
-switching to the real session.
+We can't run the `gnome-initial-setup` application with the correct user,
+since the user account does not exist yet at that time. Therefore, GDM
+runs `gnome-initial-setup` as a `gnome-initial-setup` use. When
+`gnome-inital-setup` is done, it then initiates an autologin for the newly
+created user account to switch to the ‘real’ session.
 
 Due to this arrangement, we need to copy all the settings that have been
-changed during the initial setup session from the gnome-initial-setup
+changed during the initial setup session from the `gnome-initial-setup`
 user to the real user.
 
 Mechanics
 =========
 
-To enable the initial-setup functionality in gdm, set
+By default, this functionality is enabled in GDM. To disable it, add the
+following to GDM's configuration file:
 
-InitialSetupEnable=True
+```ini
+[daemon]
+InitialSetupEnable=False
+```
 
-in the [daemon] section of /etc/gdm/custom.conf. GDM will trigger
-the initial-setup if there are no users configured yet and some other
-conditions also hold.
+(By default, this file lives at `/etc/gdm/custom.conf`, but this can be
+customized at GDM build time. For Debian-like systems, use
+`/etc/gdm3/daemon.conf`.)
+
+If enabled, GDM will trigger Initial Setup only if there are no users configured
+yet and some other conditions also hold. You can force GDM to run Initial Setup
+even if users exist by appending `gnome.initial-setup=1` to the kernel command line.
 
 The session that gdm starts for the initial-setup session is
-defined by the file /usr/share/gnome-session/sessions/gdm-setup.session.
+defined by the file
+`/usr/share/gnome-session/sessions/gnome-initial-setup.session`.
 Like the regular greeter session, it uses the desktop files in
-/usr/share/gdm/greeter/applications/.
-
-Before starting the initial-setup session, gdm copies the file
-/usr/share/gdm/20-gnome-initial-setup.rules into the polkit
-configuration to provide suitable permissions for the gnome-initial-setup
-user. The rules file is removed again together with the
-gnome-initial-setup user account.
+`/usr/share/gdm/greeter/applications/`.
 
-gnome-initial-setup also has a session mode which activates gnome-initial-setup when a user first logs in. 
The gnome-initial-setup-first-login.desktop in the
-xdg autostart directory utilises gnome-session to check if the user has a
-gnome-initial-setup-done file in their XDG_CONFIG_DIR if they don't
-gnome-initial-setup will launch with pages that are suitable for a
-non-privileged user and on exiting will write the done file.
+`gnome-initial-setup` also has an "existing user" mode which activates
+`gnome-initial-setup` when a user first logs in. The
+`gnome-initial-setup-first-login.desktop` in the
+[xdg autostart][] directory uses `gnome-session` to check if the user has a
+`gnome-initial-setup-done` file in their `XDG_CONFIG_DIR`; if they don't,
+`gnome-initial-setup` will launch with pages that are suitable for a
+non-privileged user and on exiting will write the done file.  However, since
+GNOME 40, this mode would interfere with the first-login tour
+prompt, so `gnome-initial-setup` silently writes the stamp file and exits.
 
-TODO
-====
+[xdg autostart]: https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html
+    "The Desktop Application Autostart Specification"