On Fri, Nov 04, 2022 at 03:44:17PM +0200, Jenni Nikolaenko wrote: > 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 > --- > Documentation/{ => about}/architecture.adoc | 27 ++++----- > Documentation/about/index.adoc | 32 ++++++++++ > Documentation/building-documentation.adoc | 52 ---------------- > .../decisions/001-host-update-mechanism.adoc | 4 +- > .../decisions/002-install-options.adoc | 4 +- > Documentation/decisions/003-partitioning.adoc | 2 +- > .../004-data-at-rest-encryption.adoc | 4 +- > .../005-virtual-machine-monitor.adoc | 2 +- > .../decisions/006-drivers-on-host.adoc | 2 +- > .../decisions/007-usb-virtual-machines.adoc | 2 +- > ...008-inter-vm-communication-mechanisms.adoc | 2 +- > Documentation/decisions/index.adoc | 2 +- > Documentation/{ => development}/b4.adoc | 6 +- > .../build-configuration.adoc | 13 ++-- > .../development/building-documentation.adoc | 52 ++++++++++++++++ > .../{ => development}/creating-vms.adoc | 4 +- > .../{ => development}/debugging.adoc | 12 ++-- > .../{ => development}/first-patch.adoc | 32 +++++----- > Documentation/development/index.adoc | 59 +++++++++++++++++++ > Documentation/development/managing-vms.adoc | 14 +++++ > Documentation/{ => development}/replying.adoc | 13 ++-- > .../{ => development}/reviewing-patches.adoc | 4 +- > .../{ => development}/running-vms.adoc | 4 +- > .../{ => development}/testing-patches.adoc | 28 ++++----- > Documentation/development/user-partition.adoc | 18 ++++++ > .../{ => development}/uuid-reference.adoc | 5 +- > .../development/working-with-patces.adoc | 12 ++++ > Documentation/explanation.adoc | 6 -- > Documentation/how-to.adoc | 6 -- > Documentation/index.adoc | 29 +++++++-- > .../{ => installation}/binary-cache.adoc | 22 +++++-- > .../{ => installation}/getting-spectrum.adoc | 16 ++--- > Documentation/installation/index.adoc | 23 ++++++++ > Documentation/reference.adoc | 6 -- > Documentation/tutorials.adoc | 6 -- > Documentation/user-partition.adoc | 12 ---- > 36 files changed, 350 insertions(+), 187 deletions(-) > rename Documentation/{ => about}/architecture.adoc (79%) > create mode 100644 Documentation/about/index.adoc > delete mode 100644 Documentation/building-documentation.adoc > rename Documentation/{ => development}/b4.adoc (91%) > rename Documentation/{ => development}/build-configuration.adoc (73%) > create mode 100644 Documentation/development/building-documentation.adoc > rename Documentation/{ => development}/creating-vms.adoc (97%) > rename Documentation/{ => development}/debugging.adoc (79%) > rename Documentation/{ => development}/first-patch.adoc (80%) > create mode 100644 Documentation/development/index.adoc > create mode 100644 Documentation/development/managing-vms.adoc > rename Documentation/{ => development}/replying.adoc (68%) > rename Documentation/{ => development}/reviewing-patches.adoc (88%) > rename Documentation/{ => development}/running-vms.adoc (85%) > rename Documentation/{ => development}/testing-patches.adoc (82%) > create mode 100644 Documentation/development/user-partition.adoc > rename Documentation/{ => development}/uuid-reference.adoc (97%) > create mode 100644 Documentation/development/working-with-patces.adoc > delete mode 100644 Documentation/explanation.adoc > delete mode 100644 Documentation/how-to.adoc > rename Documentation/{ => installation}/binary-cache.adoc (74%) > rename Documentation/{ => installation}/getting-spectrum.adoc (79%) > create mode 100644 Documentation/installation/index.adoc > delete mode 100644 Documentation/reference.adoc > delete mode 100644 Documentation/tutorials.adoc > delete mode 100644 Documentation/user-partition.adoc > > diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc > similarity index 79% > rename from Documentation/architecture.adoc > rename to Documentation/about/architecture.adoc > index 1c4307b..1237577 100644 > --- a/Documentation/architecture.adoc > +++ b/Documentation/about/architecture.adoc > @@ -1,32 +1,31 @@ > = Architecture > -:page-parent: Explanation > +:page-parent: About Spectrum > > // SPDX-FileCopyrightText: 2022 Unikie > // SPDX-FileCopyrightText: 2022 Alyssa Ross > // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 > > -== Introduction > +Spectrum is based on the principle of security by compartmentalization. > > -Spectrum is based on the principle of security by > -compartmentalization. The high level stack is illustrated in the > -following diagram: > +The high level stack is illustrated in the following diagram: > > -image::diagrams/stack.svg[] > +image::../diagrams/stack.svg[] > > The default set of virtual machines includes two application VMs, > _appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web > browser); and a system VM, _netvm_ (which handles hardware network > devices and provides network services to application VMs). Refer to > -xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running > +xref:../development/creating-vms.adoc[Creating VMs] and > +xref:../development/running-vms.adoc[Running > VMs] for more information about using VMs in Spectrum. > > == Architecture Decision Records (ADRs) > > https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant > -decisions] are xref:decisions/index.adoc[recorded] as lightweight > -https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs]. > +decisions] are xref:../decisions/index.adoc[recorded] as lightweight > +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[ADRs]. > > -== The Spectrum host system > +== Spectrum Host System > > Compartmentalization is implemented using > https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines. > @@ -44,7 +43,7 @@ and service scripts. > > https://wayland.freedesktop.org/[Wayland] is used for window management and > display. The Wayland architecture is well documented > -https://wayland.freedesktop.org/architecture.html[here]. The host provides only > +https://wayland.freedesktop.org/architecture.html[here]. The host provides only There's still a change from double spaced to single spaced here. I think it's the last one, but it might be a good idea to have a look through the diff to make sure that there aren't any more. > a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used > for interacting with VM consoles. In future it will be possible for application > VMs to display windows on the single Wayland compositor on the host system, > @@ -57,7 +56,7 @@ https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion > and security hardening on memory allocation]. Kernel hardening will be > investigated in future. > > -== Exploring the Spectrum dependency tree > +== Spectrum Dependency Tree > > For a detailed, interactive view of dependencies, use > https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: > @@ -66,5 +65,5 @@ https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository: > [listing] > nix-build img/live -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree > > -https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image > -interactive analysis with nix-tree] > +See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum live > +image interactive analysis with nix-tree. > diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc > new file mode 100644 > index 0000000..6961b6a > --- /dev/null > +++ b/Documentation/about/index.adoc > @@ -0,0 +1,32 @@ > += About Spectrum > +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum. > +:page-nav_order: 1 > +: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 a Linux-based system that uses the > +https://github.com/NixOS/nix[Nix package manager] and > +the https://github.com/NixOS/nixpkgs[Nix Packages collection] (Nixpkgs). I think "Packages" here should be lowercase. > + > +This gives an actively-developed base with good > +hardware support, powerful and optimised compartmentalization primitives in > +https://www.linux-kvm.org/page/Main_Page[KVM], and the reproducible packaging > +and configuration system that is important > +for a maintainable compartmentalized system. > + > +== Why Spectrum > + > +* User data and applications are managed centrally while remaining isolated. > +That means that the system can be backed up and managed as a whole, rather than > +mixed up in several dozen VMs. > + > +* The host system and isolated environments are managed declaratively and > +reproducibly using the Nix package manager. > +This can save the user the burden of maintaining many different virtual > +computers, allowing finer-grained resource access controls and making it > +possible to verify the software running across all environments. > + > +TIP: If you are interested in why we do something _this_ way instead of _that_ > +way, see xref:../decisions/index.adoc[Architecture Decision Records]. > diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc > new file mode 100644 > index 0000000..4925570 > --- /dev/null > +++ b/Documentation/development/index.adoc > @@ -0,0 +1,59 @@ > += 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. > + > + > +== General Workflow > + > +Spectrum is a very small and not changeable sort of Linux distro. It does > +not have a package manager for users. If you faced a missing feature or a bug, or you want to suggest some improvements, please consider the following: I think this page could use some more work to figure out what exactly we want to say here. Could we go with something similar to the smaller development/index.adoc page from the previous version of your patch? I don't want all your other great changes to be held up while we discuss a big new chunk of prose like this, so I'd really rather it was kept for a future, self-contained patch. > + > +* Get the latest version of the > +https://spectrum-os.org/git/spectrum[source code] and make sure your problem > +was not fixed. > +* xref:../installation/getting-spectrum.adoc[Build Spectrum] and make changes > +in the source code. In addition: > +** If you need to customize the build to be able to use a > +vendor kernel, you can > +xref:../development/build-configuration.adoc[configure the build]. > +** You can xref:../development/testing-patches.adoc[test patches] > +subbmited by others. > +* If you would like to share your code with the community, > +you can send the changes to the maintainers for possible inclusion in > +the Spectrum source code as a new patch. > +** xref:../development/b4.adoc[Install and configure the b4 utility] to be able > +to work with patches. > +** xref:../development/first-patch.adoc[Submit the changes for review]. > +Keep your git commits clean and make sure they meet general guidelines. > +** Wait for approval from the maintainers' side. Detailed updates are posted in > +Spectrum Development > +https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[threads]. > +** Update documentation with the code. For more information, see > +xref:../development/building-documentation.adoc[Building Documentation]. > + > +For additional information, see > +https://spectrum-os.org/contributing.html[Contributing to Spectrum]. > + > + > +== 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/testing-patches.adoc b/Documentation/development/testing-patches.adoc > similarity index 82% > rename from Documentation/testing-patches.adoc > rename to Documentation/development/testing-patches.adoc > index 743cd6e..0c72c93 100644 > --- a/Documentation/testing-patches.adoc > +++ b/Documentation/development/testing-patches.adoc > @@ -1,5 +1,7 @@ > = Testing Patches > -:page-parent: How-to Guides > +:page-parent: Working with Patches > +:page-grand_parent: Development > +:page-nav_order: 2 > > // SPDX-FileCopyrightText: 2022 Alyssa Ross > // SPDX-FileCopyrightText: 2022 Unikie > @@ -9,7 +11,7 @@ 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 the patch > +== Apply Patch > > . Find the patch series you want to test on > https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. > @@ -33,15 +35,15 @@ of the Spectrum root's nix-shell, which allows you to skip this step. > ---- > b4 am 20220511092352.70E54C980@atuin.qyliss.net > ---- > - > -. b4 will indicate the file name it has downloaded the patches into > - with a line like: > +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: > +---- > +. Run `git am` on that file to apply the patches. For example: > + > [example] > [source,shell] > @@ -49,14 +51,12 @@ Run `git am` on that file to apply the patches, for example: > git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx > ---- > > -== Post your test results > +== Post Your Results > > -When you've tested a patch, it's really helpful to > +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: > - > +If the patch worked for you, please reply to it and include a line like the following, separated from any reply text: This change just unwraps the line, unless I'm missing something? > diff --git a/Documentation/development/working-with-patces.adoc b/Documentation/development/working-with-patces.adoc Typo in the file name: "patces" > new file mode 100644 > index 0000000..f73734f > --- /dev/null > +++ b/Documentation/development/working-with-patces.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] > +before starting. I'm not sure this is necessary before starting — it's helpful for applying and testing other people's patches, but somebody who just wants to submit their own work doesn't need b4.