Docs: new structure

Create separate folders for new parent pages, update Introduction page,
remove a and the articles from titles, quick check text for simple english

Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
Message-Id: <20221108145228.21188-1-evgeniia.nikolaenko@unikie.com>

10 files changed, 431 insertions, 0 deletions

diff --git a/Documentation/development/b4.adoc b/Documentation/development/b4.adoc
new file mode 100644
index 0000000..5f141e9
--- /dev/null
+++ b/Documentation/development/b4.adoc
@@ -0,0 +1,51 @@
+= Installing and Configuring b4
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 1
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] is a utility
+for working with patches sent to a mailing list, such as
+https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org].
+
+NOTE: If you run `nix-shell` in the root of the Spectrum source tree,
+you'll be dropped into a development shell that has b4 set up
+correctly, and you don't need to do anything else.  You only need to
+configure it manually as described here if you want it to work outside
+of the Spectrum root's nix-shell.
+
+== Installing b4
+
+You should be able to install b4 from your package manager.
+
+Using Nix, you can start a shell with b4 available by running:
+
+[listing]
+[source,shell]
+nix-shell -p b4
+
+== Configuring b4
+
+As b4 was originally written for Linux development, it will default to
+searching for patches on the Linux mailing lists.  So to use it for
+Spectrum, it needs to be configured to search the Spectrum mailing
+lists instead.
+
+To do this, in a checkout of the appropriate git repository
+(https://spectrum-os.org/git/spectrum[Spectrum] or
+https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run:
+
+[listing]
+[source,shell]
+git config b4.midmask https://spectrum-os.org/lists/archives/spectrum-devel/%s
+
+From now on, any b4 command run in Spectrum repositories will search
+the Spectrum devel mailing list.
+
+== Using b4
+
+Using b4 to fetch and apply a patch from the Spectrum mailing list is
+described in the xref:testing-patches.adoc[Testing Patches] how-to guide.
diff --git a/Documentation/development/build-configuration.adoc b/Documentation/development/build-configuration.adoc
new file mode 100644
index 0000000..c9a8c99
--- /dev/null
+++ b/Documentation/development/build-configuration.adoc
@@ -0,0 +1,39 @@
+= Configuring the Build
+:page-parent: Development
+:page-nav_order: 1
+:example-caption: Test
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Some aspects of a Spectrum build can be customised using a build
+configuration file.
+
+By default, this configuration file should be called config.nix and located in
+the root of the Spectrum source tree, but this can be overridden by setting
+`spectrum-config` in the
+https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PATH[NIX_PATH]
+to the path of the configuration file.
+
+The configuration file should contain an attribute set.  The only
+currently allowed attribute name is `pkgs`. It allows using a
+custom Nixpkgs to evaluate Spectrum.
+
+.config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay]
+[example]
+[source,nix]
+----
+{
+  pkgs = import <nixpkgs> {
+    overlays = [
+      (final: super: {
+        weston = super.weston.overrideAttrs ({ patches ? [], ... }: {
+          patches = patches ++ [
+            path/to/weston.patch
+          ];
+        });
+      })
+    ];
+  };
+}
+----
diff --git a/Documentation/development/building-documentation.adoc b/Documentation/development/building-documentation.adoc
new file mode 100644
index 0000000..4f464f5
--- /dev/null
+++ b/Documentation/development/building-documentation.adoc
@@ -0,0 +1,52 @@
+= Building Documentation
+:page-parent: Development
+:page-nav_order: 5
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Make sure you have https://nixos.org/download.html[Nix] installed.
+You may also want to xref:../installation/binary-cache.adoc[configure the Spectrum
+binary cache], to avoid having to wait for dependencies to compile on
+your local system.
+
+. Get a copy of the Spectrum source code:
++
+[source,shell]
+----
+git clone https://spectrum-os.org/git/spectrum
+----
+. Enter the documentation directory:
++
+[source,shell]
+----
+cd spectrum/Documentation
+----
+. Enter the development environment:
++
+[source,shell]
+----
+nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+----
+. In the development shell, do an initial build of the documentation
+site:
++
+[source,shell]
+----
+scripts/build.sh
+----
+. Run a development server for previewing changes locally:
++
+[source,shell]
+----
+jekyll serve
+----
++
+This will serve a local copy of the documentation at http://localhost:4000/.
++
+IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you
+modify any of those, or add new ones, run `scripts/build.sh` again to do a full
+rebuild of the site.
+
+After making changes to the documentation, see how to
+xref:first-patch.adoc[send your patch] and submit the changes for review.
diff --git a/Documentation/development/debugging.adoc b/Documentation/development/debugging.adoc
new file mode 100644
index 0000000..f1bbf01
--- /dev/null
+++ b/Documentation/development/debugging.adoc
@@ -0,0 +1,25 @@
+= Debugging
+:page-parent: Development
+:page-nav_order: 4
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+== Extracting core dumps when running Spectrum in a VM
+
+When using a VM to run the Spectrum host system, a special mechanism
+is available to enable easy introspection of core files.
+
+When a program on the Spectrum host system dumps core, the system will
+attempt to upload the core file to _its_ host (i.e. the system running
+Spectrum in a VM) using the vsock(7) protocol, on port 1129271877.
+
+For example, when running Spectrum in a VM using `make run` in the
+host/rootfs directory (which automatically sets up a virtio-vsock
+device), the running this command on the development Linux system will
+listen for a core file from Spectrum, and write it to a file:
+
+[source,shell]
+----
+socat -u VSOCK-LISTEN:1129271877 CREATE:spectrum.core
+----
diff --git a/Documentation/development/first-patch.adoc b/Documentation/development/first-patch.adoc
new file mode 100644
index 0000000..aa6ebee
--- /dev/null
+++ b/Documentation/development/first-patch.adoc
@@ -0,0 +1,100 @@
+= Sending Your Patch
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 1
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+This tutorial assumes that you already have basic
+https://git-scm.com/[git] experience.
+
+Before beginning, you'll need to have a local git checkout of the
+https://spectrum-os.org/git/[Spectrum source tree].  You'll also need
+to have configured `git send-email` — a guide for this can be found at
+https://git-send-email.io/.
+
+== Making Changes
+
+The process of making changes is similar to working on any git repository.
+
+. Create a branch for your changes:
++
+[source,shell]
+----
+git checkout -b fix-docs # for example
+----
+. Make changes in your editor.
+. Stage and commit your changes:
++
+[source,shell]
+----
+git add Documentation/first-patch.adoc # for example
+git commit -s
+----
++
+TIP: The `-s` option adds a `Signed-off-by` line to the commit.  This
+indicates your acceptance of the
+https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's
+Certificate of Origin], which is mandatory for Spectrum patches.
+
+== Submitting Changes
+
+Once you're happy with how the commits on your branch look, run:
+
+[source,shell]
+----
+git send-email --to devel@spectrum-os.org --confirm=always origin/main
+----
+
+For each message, you will be prompted for confirmation, and then the
+change will be submitted to the Spectrum development mailing list.
+They will appear shortly on the
+https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[web
+interface].
+
+[#cover-letter]
+TIP: If you're submitting multiple changes, and you'd like to provide
+an overall description for the whole series, you can add the
+`--compose` option, which will prompt you to compose a "cover letter"
+message that will be sent before all of your patches.
+
+== Feedback
+
+Once your patch has been submitted, wait for it to be reviewed.
+Feedback, if any, will be sent as email replies to your submitted
+patch.  You can respond to feedback in your mail client.
+
+Use the *Reply All* button to sent your messages to the
+mailing list as well as to the person who sent the feedback.
+
+If you need to make changes to your patch and submit a new version,
+use https://git-rebase.io/[`git rebase`] to create a new version of
+your patch(es) and then submit it like this:
+
+[source,shell]
+----
+git send-email -v2 --to devel@spectrum-os.org --confirm=always origin/main
+----
+
+The added `-v2` flag indicates that this is version two of your
+patch set.  If your patches require more rounds of changes, submit
+subsequent rounds with `-v3`, `-v4`, etc. as appropriate.
+
+If you would like to describe what has changed from the previous version
+of your patches, you can do so in a xref:cover-letter[cover letter]
+as described above.
+
+== Acceptance
+
+Once your patch has been accepted, it will be applied to the upstream
+Spectrum git repository.  You will receive an automated email
+confirmation when this happens.
+
+== Questions
+
+If you have any questions about the patch submission process, you can
+ask them either on the
+https://spectrum-os.org/participating.html#spectrum-devel[development
+mailing list], or in the
+https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].
diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
new file mode 100644
index 0000000..1fccdd5
--- /dev/null
+++ b/Documentation/development/index.adoc
@@ -0,0 +1,27 @@
+= Development
+:description: Development progress, general development practices
+:page-nav_order: 4
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Spectrum is free software, currently under active development.
+
+
+== Developer Setup
+
+* https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4]
+* https://nixos.org/manual/nix/stable/introduction.html[Nix package manager]
+* https://docs.asciidoctor.org/[AsciiDoc] for writing the documentation
+
+
+== Mailing Lists
+
+The Spectrum project runs several
+https://spectrum-os.org/participating.html#mailing-lists[mailing lists] on
+which you can ask your questions or help other people with the questions they
+have.  All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists.
+
+For real-time feedback, use
+https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].
diff --git a/Documentation/development/replying.adoc b/Documentation/development/replying.adoc
new file mode 100644
index 0000000..a1ad394
--- /dev/null
+++ b/Documentation/development/replying.adoc
@@ -0,0 +1,27 @@
+= Replying to Messages in the Mailing List Archives
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 3
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Discussion of Spectrum takes place on
+https://spectrum-os.org/participating.html#mailing-lists[mailing
+lists].
+
+Make sure to Reply All when replying to messages, so that the message
+is sent to the mailing list and not just to the person you reply to.
+
+== Getting a copy of a message
+
+You may want to reply to a mailing list message that you do not have a
+copy of in your mail client, because you are not subscribed to the
+list or because you subscribed after the message was sent.
+
+To do this, find the message you want to reply to in the
+https://spectrum-os.org/lists/archives[public-inbox list archives],
+click on the "reply" link at the bottom of the message, then click the
+"mbox" link.  Save the result to a file, then open it in your mail
+client.  This should import the message and allow you to Reply All to
+it as normal.
diff --git a/Documentation/development/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc
new file mode 100644
index 0000000..ba47f25
--- /dev/null
+++ b/Documentation/development/reviewing-patches.adoc
@@ -0,0 +1,22 @@
+= Reviewing Patches
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 2
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+To review a patch posted to the
+https://spectrum-os.org/participating.html#spectrum-devel[mailing
+list], xref:replying.adoc[reply] to it with your feedback.
+
+If you believe the patch is acceptable and should be included in
+Spectrum, include a line in your reply like this:
+
+[example]
+[listing]
+Reviewed-by: John Smith <john@example.com>
+
+This format is recognized by tooling, so any lines in this format in
+patch replies will be automatically included in the commit message
+when a patch is applied.
diff --git a/Documentation/development/testing-patches.adoc b/Documentation/development/testing-patches.adoc
new file mode 100644
index 0000000..0c72c93
--- /dev/null
+++ b/Documentation/development/testing-patches.adoc
@@ -0,0 +1,76 @@
+= Testing Patches
+:page-parent: Working with Patches
+:page-grand_parent: Development
+:page-nav_order: 2
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Potential changes to Spectrum are posted to and discussed on the
+https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org]
+mailing list.
+
+== Apply Patch
+
+. Find the patch series you want to test on
+  https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox].
+. Navigate to the "permalink" page for any patch in the series.
+. Copy the Message-Id for the patch, as shown on the permalink page, e.g.
+  \20220511092352.70E54C980@atuin.qyliss.net.
+. In a checkout of the https://spectrum-os.org/git/spectrum[Spectrum]
+  git repository, run `nix-shell` to enter a shell environment with b4
+  set up correctly for Spectrum.
++
+TIP: You can manually xref:b4.adoc[set up b4] so that it works outside
+of the Spectrum root's nix-shell, which allows you to skip this step.
+. In a checkout of the appropriate git repository
+  (https://spectrum-os.org/git/spectrum[Spectrum] or
+  https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run `b4 am`
+  with the patch's Message-Id to download all the patches in the
+  series into a file.
++
+[example]
+[source,shell]
+----
+b4 am 20220511092352.70E54C980@atuin.qyliss.net
+----
+b4 will indicate the file name it has downloaded the patches into with a line
+like:
++
+[example]
+[listing]
+----
+Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
+----
+. Run `git am` on that file to apply the patches. For example:
++
+[example]
+[source,shell]
+----
+git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx
+----
+
+== Post Your Results
+
+When you tested a patch, it is helpful to
+xref:replying.adoc[reply] with your test results.
+
+If the patch worked for you, please reply to it and include a line like the following, separated from any reply text:
+----
+Tested-by: John Smith <john@example.com>
+----
+
+This format is recognized by tooling, so any lines in this format in
+patch replies will be automatically included in the commit message
+when a patch is applied.
+
+It's also helpful to explain in your reply how you tested the patch,
+but you don't have to if it's obvious.  For example, if a patch is
+supposed to fix a bug, and you verified that after applying the patch
+the bug is fixed, just the Tested-by line on its own is enough to
+indicate that.
+
+If you found an issue with the patch, do not include a Tested-by line,
+and instead reply to the patch explaining what you tested, what you
+expected to happen, and what actually happened.
diff --git a/Documentation/development/working-with-patches.adoc b/Documentation/development/working-with-patches.adoc
new file mode 100644
index 0000000..a2694ed
--- /dev/null
+++ b/Documentation/development/working-with-patches.adoc
@@ -0,0 +1,12 @@
+= Working with Patches
+:page-parent: Development
+:page-nav_order: 3
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Patches are the way for contributors to submit code to the Spectrum project.
+
+Make sure to xref:../development/b4.adoc[install and configure the b4 utility]
+for applying and testing other people's patches.