From mboxrd@z Thu Jan 1 00:00:00 1970 Date: Tue, 8 Nov 2022 09:04:39 +0000 From: Alyssa Ross To: Jenni Nikolaenko Cc: devel@spectrum-os.org Subject: Re: [PATCH v3] Docs: new structure Message-ID: <20221108090439.gi57cr6igmcaoxkc@x220> References: <20221104134417.703042-1-evgeniia.nikolaenko@unikie.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="4eihuoapzrgk7k5a" Content-Disposition: inline In-Reply-To: <20221104134417.703042-1-evgeniia.nikolaenko@unikie.com> List-Id: --4eihuoapzrgk7k5a Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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/{ =3D> 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/{ =3D> development}/b4.adoc | 6 +- > .../build-configuration.adoc | 13 ++-- > .../development/building-documentation.adoc | 52 ++++++++++++++++ > .../{ =3D> development}/creating-vms.adoc | 4 +- > .../{ =3D> development}/debugging.adoc | 12 ++-- > .../{ =3D> development}/first-patch.adoc | 32 +++++----- > Documentation/development/index.adoc | 59 +++++++++++++++++++ > Documentation/development/managing-vms.adoc | 14 +++++ > Documentation/{ =3D> development}/replying.adoc | 13 ++-- > .../{ =3D> development}/reviewing-patches.adoc | 4 +- > .../{ =3D> development}/running-vms.adoc | 4 +- > .../{ =3D> development}/testing-patches.adoc | 28 ++++----- > Documentation/development/user-partition.adoc | 18 ++++++ > .../{ =3D> development}/uuid-reference.adoc | 5 +- > .../development/working-with-patces.adoc | 12 ++++ > Documentation/explanation.adoc | 6 -- > Documentation/how-to.adoc | 6 -- > Documentation/index.adoc | 29 +++++++-- > .../{ =3D> installation}/binary-cache.adoc | 22 +++++-- > .../{ =3D> 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/{ =3D> about}/architecture.adoc (79%) > create mode 100644 Documentation/about/index.adoc > delete mode 100644 Documentation/building-documentation.adoc > rename Documentation/{ =3D> development}/b4.adoc (91%) > rename Documentation/{ =3D> development}/build-configuration.adoc (73%) > create mode 100644 Documentation/development/building-documentation.adoc > rename Documentation/{ =3D> development}/creating-vms.adoc (97%) > rename Documentation/{ =3D> development}/debugging.adoc (79%) > rename Documentation/{ =3D> development}/first-patch.adoc (80%) > create mode 100644 Documentation/development/index.adoc > create mode 100644 Documentation/development/managing-vms.adoc > rename Documentation/{ =3D> development}/replying.adoc (68%) > rename Documentation/{ =3D> development}/reviewing-patches.adoc (88%) > rename Documentation/{ =3D> development}/running-vms.adoc (85%) > rename Documentation/{ =3D> development}/testing-patches.adoc (82%) > create mode 100644 Documentation/development/user-partition.adoc > rename Documentation/{ =3D> 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/{ =3D> installation}/binary-cache.adoc (74%) > rename Documentation/{ =3D> 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/archit= ecture.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 @@ > =3D 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 > > -=3D=3D 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. > > =3D=3D Architecture Decision Records (ADRs) > > https://en.wikipedia.org/wiki/Architectural_decision[Architecturally sig= nificant > -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]. > > -=3D=3D The Spectrum host system > +=3D=3D 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 provi= des only > +https://wayland.freedesktop.org/architecture.html[here]. The host provid= es 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 app= lication > VMs to display windows on the single Wayland compositor on the host syst= em, > @@ -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. > > -=3D=3D Exploring the Spectrum dependency tree > +=3D=3D 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 Sp= ectrum repository: > [listing] > nix-build img/live -I nixpkgs=3Dhttps://spectrum-os.org/git/nixpkgs/snap= shot/nixpkgs-rootfs.tar.gz --no-out-link | xargs -o nix-tree > > -https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live i= mage > -interactive analysis with nix-tree] > +See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum l= ive > +image interactive analysis with nix-tree. > diff --git a/Documentation/about/index.adoc b/Documentation/about/index.a= doc > new file mode 100644 > index 0000000..6961b6a > --- /dev/null > +++ b/Documentation/about/index.adoc > @@ -0,0 +1,32 @@ > +=3D About Spectrum > +:description: Some words about Spectrum as the operating system, not a p= roject. Highlights the differences between common Linux distributions and S= pectrum. > +: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 pack= aging > +and configuration system that is important > +for a maintainable compartmentalized system. > + > +=3D=3D Why Spectrum > + > +* User data and applications are managed centrally while remaining isola= ted. > +That means that the system can be backed up and managed as a whole, rath= er 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/develop= ment/index.adoc > new file mode 100644 > index 0000000..4925570 > --- /dev/null > +++ b/Documentation/development/index.adoc > @@ -0,0 +1,59 @@ > +=3D 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. > + > + > +=3D=3D General Workflow > + > +Spectrum is a very small and not changeable sort of Linux distro. It do= es > +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 follo= wing: 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 pro= blem > +was not fixed. > +* xref:../installation/getting-spectrum.adoc[Build Spectrum] and make ch= anges > +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 p= osted in > +Spectrum Development > +https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[thr= eads]. > +** 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]. > + > + > +=3D=3D Developer Setup > + > +* https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] > +* https://nixos.org/manual/nix/stable/introduction.html[Nix package mana= ger] > +* https://docs.asciidoctor.org/[AsciiDoc] for writing the documentation > + > + > +=3D=3D 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 S= pectrum 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/developme= nt/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 @@ > =3D 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 discusse= d on the > https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum= -os.org] > mailing list. > > -=3D=3D Apply the patch > +=3D=3D 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 e= xample: > git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx > ---- > > -=3D=3D Post your test results > +=3D=3D 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/Documen= tation/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 @@ > +=3D 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 proj= ect. > + > +Make sure to xref:../development/b4.adoc[install and configure the b4 ut= ility] > +before starting. I'm not sure this is necessary before starting =E2=80=94 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. --4eihuoapzrgk7k5a Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEH9wgcxqlHM/ARR3h+dvtSFmyccAFAmNqG6QACgkQ+dvtSFmy ccAllQ//Vi8FfUHJrJpRtejAtHwWtMTxPMFNP8WCG8up/x88vlsqNPqRGo7MGNOg 2ompLnrw34g1QFs7mAEGZDeNfvJQ7IqVVikrtxIwO4W+DNfQ0noJfNu2a1qrKM2U +YfZoQ9UroATfWtMp38/I+/eusLaHFGkwkvuhGORXPYY+y/0h6SOkMFESUSvE1s4 QfIF7bcSYzrzE8mfNFHHh+pEeYwNYJjD2/bFund6I1g/GVdRhH/TOMwtkfIIgf+n kp4S7AK3Df88sDwQvL/nxfbEtqIoA71wLLHDyPJHwrKwrF8IudSzI63yKTU3i9/i ydWzLSfUHhotM4GIFrRWB+19WWIo6ssm/Yg2/VjkfUhQAqS7iVzzOJAT5R4WFoBI Z3SuOdLTzQNggKHoc4QFssZIXM+6KWCtuMUbKJ4YmN2ni4pSAho1+5WpGLSzq836 CCUVVR1vYJDaHUGfbN0/VRKcPGLrP8KJzlf3E0SLDYIxSZTjNfFIqlZ4e9ghdNOZ UglFCKAmUyXqEDFtUz/lqvli0k3OqXYqZM8SHy+XZgyF/wiz/lP7TGp8yfXVUESw wa+E7zFVeXcYYZxdtQhD8BFo99AtAXsa/Pj3aLVCabplkljEUwF0lJPOo3U16bdY iE+jv9nfjX/W8++aBIcxlZwsG/ImoavJ6qY01xT0hRZcxg0XeRo= =3TIy -----END PGP SIGNATURE----- --4eihuoapzrgk7k5a--