From: Alyssa Ross <alyssa.ross@unikie.com>
To: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
Cc: devel@spectrum-os.org
Subject: Re: [PATCH v3] Docs: new structure
Date: Tue, 8 Nov 2022 09:04:39 +0000 [thread overview]
Message-ID: <20221108090439.gi57cr6igmcaoxkc@x220> (raw)
In-Reply-To: <20221104134417.703042-1-evgeniia.nikolaenko@unikie.com>
[-- Attachment #1: Type: text/plain, Size: 16624 bytes --]
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.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2022-11-08 9:04 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-04 13:44 Jenni Nikolaenko
2022-11-04 13:58 ` Jenni Nikolaenko
2022-11-08 9:04 ` Alyssa Ross [this message]
2022-11-08 15:02 ` Jenni Nikolaenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221108090439.gi57cr6igmcaoxkc@x220 \
--to=alyssa.ross@unikie.com \
--cc=devel@spectrum-os.org \
--cc=evgeniia.nikolaenko@unikie.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).