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 <evgeniia.nikolaenko@unikie.com> --- 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 <hi@alyssa.is> // 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 <hi@alyssa.is> // 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.