From: Alyssa Ross <alyssa.ross@unikie.com>
To: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
Cc: devel@spectrum-os.org
Subject: Re: [PATCH] Docs: new structure
Date: Tue, 1 Nov 2022 12:13:35 +0000 [thread overview]
Message-ID: <20221101121335.7zh7kxcnxyrojdfp@x220> (raw)
In-Reply-To: <20221028110558.205351-1-evgeniia.nikolaenko@unikie.com>
[-- Attachment #1: Type: text/plain, Size: 16688 bytes --]
Hi Jenni, thank you for the new patch! I really like where this is
going, and the comments I have this time should almost all be small
things that are easy to fix.
BTW: when you submit the next version of your patch, please add a -v3
argument to your git send-email command to mark it as version 3, to make
it easier for people following the progress of the patch (like me!) to
keep the different versions straight. More info here:
https://spectrum-os.org/doc/first-patch.html#feedback
On Fri, Oct 28, 2022 at 02:05:58PM +0300, 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>
> ---
>
> diff --git a/Documentation/architecture.adoc b/Documentation/about/architecture.adoc
> similarity index 84%
> rename from Documentation/architecture.adoc
> rename to Documentation/about/architecture.adoc
> index 1c4307b..c1af320 100644
> --- a/Documentation/architecture.adoc
> +++ b/Documentation/about/architecture.adoc
> @@ -35,7 +33,7 @@ https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
> Machine] (KVM) to provide lightweight, hardware-accelerated VMs.
>
> While Linux (including KVM) is portable between many hardware architectures,
> -cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only
> +cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only
This is one of a few sentences that the patch still changes to be
single-spaced.
> works on x86_64, but aarch64 support is in development.
>
> https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
> diff --git a/Documentation/about/index.adoc b/Documentation/about/index.adoc
> new file mode 100644
> index 0000000..9e2a47e
> --- /dev/null
> +++ b/Documentation/about/index.adoc
> @@ -0,0 +1,30 @@
> += About Spectrum
> +:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
Let's wrap these at 70-80 characters too. There's an example in the
AsciiDoctor documentation of how to do it (looks like it needs
backslashes at the end of lines):
https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description
> +: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 Nix package manager and Nixpkgs
> +collection of packages.
*The* Nix package manager, and *the* Nixpkgs package collection.
Maybe we could link to them too?
> +
> +This gives an actively-developed base with good
> +hardware support, powerful and optimised compartmentalization primitives in
> +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].
This whole page is excellent, thanks a lot!
> diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
> new file mode 100644
> index 0000000..1fe4d8b
> --- /dev/null
> +++ b/Documentation/development/index.adoc
> @@ -0,0 +1,31 @@
> += 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.
> +
> +If you made changes in a source code,
> +https://spectrum-os.org/installation/getting-spectrum.html#building-an-installer[rebuild Spectrum],
> +xref:../development/testing-patches.adoc[test your patch] and
testing-patches.adoc is about testing patches submitted by other people,
so I don't think it makes sense to link to it in this context.
> +then https://spectrum-os.org/development/first-patch.html#submitting-changes[submit your changes for review].
> +
> +== Developer Setup
> +
> +Before starting, make sure you are familiar with
> +https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] and the
Ideally I'd like it if the documentation didn't assume familiarity with
b4, because lots of people won't have used it before, it's not too well
documented, and using it with Spectrum only requires learning a couple
of commands. So let's try to instead just explain everything about it
somebody using it with Spectrum would need to know in our documentation?
If there's missing info about it I can try to expand what we have.
> +https://nixos.org/manual/nix/stable/introduction.html[Nix package manager].
> +
> +== Mailing Lists
> +
> +The Spectrum project runs several
> +https://spectrum-os.org/mailman3/lists/?all-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 81%
> rename from Documentation/testing-patches.adoc
> rename to Documentation/development/testing-patches.adoc
> index 743cd6e..600cf0f 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].
> @@ -28,35 +30,31 @@ of the Spectrum root's nix-shell, which allows you to skip this step.
> with the patch's Message-Id to download all the patches in the
> series into a file.
> +
> -[example]
My comments from the previous version still apply here — this [example]
attribute shouldn't be removed, …
> [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:
> +b4 will indicate the file name it has downloaded the patches into with a line
> +like:
> +
> -[example]
> -[listing]
> +[source,shell]
… and this was also correct before.
> +----
> 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]
> ----
> 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:
> +[source,shell]
This isn't shell source code, so we shouldn't use this attribute here.
> ----
> Tested-by: John Smith <john@example.com>
> ----
> @@ -66,10 +64,10 @@ 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
> +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.)
> +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
> diff --git a/Documentation/explanation.adoc b/Documentation/explanation.adoc
> index b39cc6d..f682129 100644
> --- a/Documentation/explanation.adoc
> +++ b/Documentation/explanation.adoc
> @@ -1,6 +1,5 @@
> = Explanation
> -:page-has_children: true
> -:page-nav_order: 4
> +:page-nav_exclude: true
Since there's no way to find them in the navigation, and they don't
have any content or child pages, should we just delete these Diátaxis
category pages?
>
> // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> diff --git a/Documentation/getting-started/index.adoc b/Documentation/getting-started/index.adoc
> new file mode 100644
> index 0000000..639e0a6
> --- /dev/null
> +++ b/Documentation/getting-started/index.adoc
> @@ -0,0 +1,14 @@
> += Getting Started
> +:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth). Ready to get started with Spectrum OS? After installing you can create VMs and then configure each one.
Spectrum, not Spectrum OS. :)
> +:page-nav_order: 3
> +:page-has_children: true
> +:page-has_toc: false
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Ready to get started with Spectrum? Here is what you can do next:
> +
> +* xref:../getting-started/creating-vms.adoc[Create your own VM] to use others applications.
> +* xref:../getting-started/running-vms.adoc[Start some applications].
> +* If needed, xref:../getting-started/user-partition.adoc[change the user partition type].
I don't think this last thing is something that an end user is likely to
want to do — it's really a development convenience.
> diff --git a/Documentation/index.adoc b/Documentation/index.adoc
> index 3079847..ea28533 100644
> --- a/Documentation/index.adoc
> +++ b/Documentation/index.adoc
> @@ -1,13 +1,32 @@
> -= Spectrum Docs
> += Spectrum Documentation
> :page-nav_exclude: true
>
> // 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
>
> -Spectrum is a compartmentalized operating system.
>
> -If you'd like to try Spectrum, see xref:getting-spectrum.adoc[Getting
> -Spectrum].
> +Spectrum is an open-source project that aims to create a computer operating
> +system, based on the principle of security by compartmentalization, that has a
> +lower barrier to entry and is easy to use and maintain.
> +
> +== Using Spectrum
>
> To learn about what Spectrum is and how it's implemented, start with
> -the xref:architecture.adoc[architecture overview].
> +the xref:about/architecture.adoc[architecture overview].
> +
> +If you want to try Spectrum, see xref:../installation/index.adoc[Build and Run]
> + to setup a development environment.
> +
> +
> +== Developing and Contributing
> +
> +Spectrum is made of free and open-source software. It is free for anyone to
> + use, modify, and distribute.
> +
> +Once you are up and rinning, see
typo: rinning
> + xref:../development/index.adoc[Development] to understand how to work with
> + patches, debug the system or build the documentation.
Let's maybe be a bit less specific about what's in the development
section? These three things are things that we have documented right
now, but as the documentation fills up these probably won't be the most
important three things somebody might be looking for.
> +
> +If you are thinking of contributing to Spectrum docs, see
> + xref:../development/building-documentation.adoc[Building Documentation].
> diff --git a/Documentation/binary-cache.adoc b/Documentation/installation/binary-cache.adoc
> similarity index 80%
> rename from Documentation/binary-cache.adoc
> rename to Documentation/installation/binary-cache.adoc
> index 6e69b39..dff12e1 100644
> --- a/Documentation/binary-cache.adoc
> +++ b/Documentation/installation/binary-cache.adoc
> @@ -1,5 +1,6 @@
> -= Setting Up the Binary Cache
> -:page-parent: How-to Guides
> += Setting Up Binary Cache
> +:page-parent: Build and Run
> +:page-nav_order: 1
>
> // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
> // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> @@ -20,10 +21,9 @@ encounter any trouble with it.
> The binary cache is currently not able to provide logs, due to a
> https://github.com/NixOS/nix/pull/6051[Nix bug].
>
> -== On NixOS
> +== For NixOS
>
> -The following configuration adds the Spectrum binary cache as a
> -substituter, and tells Nix to trust builds signed with its public key.
> +Add the following configuration to /etc/nixos/configuration.nix:
>
> [source,nix]
> ----
> @@ -38,7 +38,13 @@ substituter, and tells Nix to trust builds signed with its public key.
> }
> ----
>
> -== On Non-NixOS systems
> +This configuration adds the Spectrum binary cache as a substituter and makes
> +Nix to trust builds signed with its public key.
"makes Nix to trust" is ungrammatical. This should be
"tells Nix to trust" or "makes Nix trust".
> +
> +To apply changes, rebuild your system with the https://nixos.wiki/wiki/Nixos-rebuild[nixos-rebuild] command.
> +
> +
> +== For Non-NixOS Systems
>
> Add the following configuration to /etc/nix/nix.conf:
>
> diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
> new file mode 100644
> index 0000000..2c4e9c7
> --- /dev/null
> +++ b/Documentation/installation/index.adoc
> @@ -0,0 +1,26 @@
> += Build and Run
> +:description: How to download and install Spectrum OS.
> +:page-nav_order: 2
> +:page-has_children: true
> +:page-has_toc: false
> +
> +// SPDX-FileCopyrightText: 2022 Unikie
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +
> +To start working with Spectrum, you need:
> +
> +* xref:../installation/binary-cache.adoc[Set up the binary cache] to speed up the build process.
> +* xref:../installation/getting-spectrum.adoc[Build Spectrum] from the source.
> +* xref:../installation/b4.adoc[Install and configure the b4 utility] to be able to work with patches.
b4 is a development tool, so people don't need to wory about it to
install Spectrum. And the getting-spectrum.adoc document already
explains about the binary cache, so I think we should just link to
getting-spectrum.adoc here.
> +
> +TIP: Currently, Spectrum works only on x86-64. AAarch64 support is in
> +development. If you have the configuration layer, you can
> +xref:../development/build-configuration.adoc[configure the build] to be able to
> +work with specific devices.
One too many "a"s here — it's "aarch64".
"If you have the configuration layer" doesn't really make sense to me.
Maybe we could say:
If you need to customise the build, for example to use a vendor kernel,
you can use a xref:../development/bulid-configuration.adoc[build
configuration file].
> +
> +== Uninstalling and Updating
> +
> +Currently, there is no implementation for a software update.
> +
> +You can replace Spectrum by installing another OS.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2022-11-01 12:13 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <RE: [PATCH] Docs: new structure>
2022-10-28 11:05 ` Jenni Nikolaenko
2022-10-28 11:24 ` Jenni Nikolaenko
2022-11-01 12:14 ` Alyssa Ross
2022-11-01 12:13 ` Alyssa Ross [this message]
2022-11-04 13:57 ` Jenni Nikolaenko
2022-11-08 9:03 ` Alyssa Ross
2022-11-08 15:05 ` Jenni Nikolaenko
2022-09-06 13:55 Jenni Nikolaenko
2022-09-19 9:30 ` Alyssa Ross
2022-09-28 12:52 ` Jenni N
2022-09-29 8:58 ` Alyssa Ross
2022-10-28 11:22 ` 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=20221101121335.7zh7kxcnxyrojdfp@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).