Merge pull request #3185 from travier/main-docs-spdx-fixes

Docs fixes & SPDX identifiers uniformisation

README.md

@@ -75,7 +75,10 @@ their host system as well as Flatpak.
 [Liri OS](https://liri.io/download/silverblue/) has the option to install
 their distribution using ostree.
 
-[Torizon OS](https://developer.toradex.com/torizon/torizoncore/torizoncore-technical-overview/) is a Linux distribution for embedded systems that updates via OSTree images delivered via [Uptane](https://uptane.github.io/) and [aktualizr](https://github.com/uptane/aktualizr/).
+[Torizon OS](https://developer.toradex.com/torizon/torizoncore/torizoncore-technical-overview/)
+is a Linux distribution for embedded systems that updates via OSTree images
+delivered via [Uptane](https://uptane.github.io/) and
+[aktualizr](https://github.com/uptane/aktualizr/).
 
 ## Distribution build tools
 
@@ -121,7 +124,10 @@ use the "libostree host system" aspects (e.g. bootloader management), just the
 "git-like hardlink dedup". For example, Flatpak supports a per-user OSTree
 repository.
 
-[aktualizr](https://github.com/uptane/aktualizr/) is an [Uptane](https://uptane.github.io/)-conformant software update client library intended for use in automotive and other security-sensitive embedded devices. It uses OSTree to manage the OS of the host device by default.
+[aktualizr](https://github.com/uptane/aktualizr/) is an
+[Uptane](https://uptane.github.io/)-conformant software update client library
+intended for use in automotive and other security-sensitive embedded devices.
+It uses OSTree to manage the OS of the host device by default.
 
 ## Language bindings
 

docs/CONTRIBUTING.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 190
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Contributing
 {: .no_toc }

docs/README-historical.md

@@ -2,6 +2,7 @@
 nav_order: 990
 title: Historical OSTree README
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 **This file is outdated, but some of the text here is still useful for
 historical context.  I'm preserving it (explicitly still in the tree)

docs/README.md

@@ -1,3 +1,5 @@
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
+
 This documentation is written in [Jekyll](https://jekyllrb.com/) format
 to be published on [GitHub Pages](https://pages.github.com/). The
 rendered HTML will be automatically built and published, but you can

docs/adapting-existing.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 70
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Adapting existing mainstream distributions
 {: .no_toc }
@@ -200,6 +201,3 @@ Then to actually deploy this tree for the next boot:
 
 This is essentially what [rpm-ostree](https://github.com/projectatomic/rpm-ostree/)
 does to support its [package layering model](https://rpm-ostree.readthedocs.io/en/latest/manual/administrator-handbook/#hybrid-imagepackaging-via-package-layering).
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/atomic-rollbacks.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 60
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Atomic Rollbacks
 {: .no_toc }
@@ -171,6 +172,3 @@ ExecStart=/usr/sbin/ostree-rollback-to-rescue
 [Install]
 WantedBy=sysinit.target
 ```
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/atomic-upgrades.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 50
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Atomic Upgrades
 {: .no_toc }
@@ -140,6 +141,3 @@ so just like `/boot`, it has a version of `0` or `1` appended.
 Each bootloader entry has a special `ostree=` argument which refers to
 one of these symbolic links.  This is parsed at runtime in the
 initramfs.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/authenticated-repos.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 100
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Handling access to authenticated remote repositories
 {: .no_toc }
@@ -8,7 +9,6 @@ nav_order: 100
 1. TOC
 {:toc}
 
-
 There is no default concept of an "ostree server"; ostree expects to talk to a generic webserver, so any tool and technique applicable for generic HTTP can also apply to fetching content via OSTree's builtin HTTP client.
 
 ## Using mutual TLS
@@ -24,5 +24,3 @@ The client supports HTTP `basic` authentication, but this has well-known managem
 ## Using cookies
 
 Since [this pull request](https://github.com/ostreedev/ostree/pull/531) ostree supports adding cookies to a remote configuration.  This can be used with e.g. [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-signed-cookies.html).
-
-

docs/bootloaders.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 120
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Bootloaders
 {: .no_toc }

docs/buildsystem-and-repos.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 90
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Writing a buildsystem and managing repositories
 {: .no_toc }
@@ -191,6 +192,3 @@ ostree --repo=repo static-delta generate exampleos/x86_64/standard
 
 Next, see [Repository Management](repository-management.md) for the
 next steps in managing content in OSTree repositories.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/composefs.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 110
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Using composefs with OSTree
 {: .no_toc }
@@ -113,6 +114,3 @@ provides much stronger and more efficient integrity:
 
 - https://github.com/containers/composefs
 - https://www.kernel.org/doc/html/next/filesystems/fsverity.html
-
-<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
-

docs/contributing-tutorial.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 200
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # OSTree Contributing Tutorial
 {: .no_toc }

docs/deployment.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 40
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Deployments
 {: .no_toc }
@@ -124,6 +125,3 @@ deployment.
 At present, not all bootloaders implement the BootLoaderSpec, so
 OSTree contains code for some of these to regenerate native config
 files (such as `/boot/syslinux/syslinux.conf`) based on the entries.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/formats.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 80
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # OSTree data formats
 {: .no_toc }
@@ -204,6 +205,3 @@ For these types of objects, the delta superblock contains an array of
 "fallback objects".  These objects aren't included in the delta
 parts - the client simply fetches them from the underlying `.filez`
 object.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/ima.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 110
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Using Linux IMA with OSTree
 {: .no_toc }
@@ -110,6 +111,3 @@ signing commits with these "portable" EVM signatures in addition to IMA.
 - https://wiki.gentoo.org/wiki/Integrity_Measurement_Architecture
 - https://fedoraproject.org/wiki/Changes/Signed_RPM_Contents
 - https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_monitoring_and_updating_the_kernel/enhancing-security-with-the-kernel-integrity-subsystem_managing-monitoring-and-updating-the-kernel
-
-<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
-

docs/index.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 10
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # libostree
 {: .no_toc }
@@ -36,17 +37,24 @@ version of
  - Binary history on the server side (and client)
  - Introspectable shared library API for build and deployment systems
  - Flexible support for multiple branches and repositories, supporting
-   projects like [flatpak](https://github.com/flatpak/flatpak) which
+   projects like [Flatpak](https://github.com/flatpak/flatpak) which
    use libostree for applications, rather than hosts.
 
 ## Operating systems and distributions using OSTree
 
+[Apertis](https://www.apertis.org/) uses libostree for their host system as
+well as Flatpak. See [update documentation](https://www.apertis.org/guides/ostree/) and
+[apertis-update-manager](https://gitlab.apertis.org/pkg/apertis-update-manager)
+
 [Endless OS](https://endlessos.com/) uses libostree for their host system as
-well as flatpak. See
+well as Flatpak. See
 their [eos-updater](https://github.com/endlessm/eos-updater)
 and [deb-ostree-builder](https://github.com/dbnicholson/deb-ostree-builder)
 projects.
 
+For Debian/apt, see also https://github.com/stb-tester/apt2ostree
+and the LWN article [Merkle trees and build systems](https://lwn.net/Articles/821367/).
+
 Fedora derivatives use rpm-ostree (noted below); there are 4 variants using OSTree:
 
  - [Fedora CoreOS](https://getfedora.org/en/coreos/)
@@ -59,16 +67,22 @@ The [machine-config-operator](https://github.com/openshift/machine-config-operat
 manages upgrades.  RHEL CoreOS is also the successor to RHEL Atomic Host, which
 uses rpm-ostree as well.
 
+[Red Hat In-Vehicle Operating System (RHIVOS)](https://www.redhat.com/en/blog/new-standard-red-hat-vehicle-operating-system-modern-and-future-vehicles) is a derivative of CentOS Automotive Stream Distribution that uses OSTree, it's closest Fedora derivative is Fedora IoT although it was created as it's own distribution.
+
 [GNOME Continuous](https://wiki.gnome.org/Projects/GnomeContinuous) is
 where OSTree was born - as a high performance continuous delivery/testing
 system for GNOME.
 
+[GNOME OS](https://os.gnome.org/) is a testing OS that uses libostree for
+their host system as well as Flatpak.
+
 [Liri OS](https://liri.io/download/silverblue/) has the option to install
 their distribution using ostree.
 
-[Torizon OS](https://developer.toradex.com/torizon/torizoncore/)
-uses libostree and Aktualizr as the base for OTA updates from compatible
-platforms, including [Torizon Cloud](https://developer.toradex.com/torizon/torizon-platform/torizon-platform-services-overview).
+[Torizon OS](https://developer.toradex.com/torizon/torizoncore/torizoncore-technical-overview/)
+is a Linux distribution for embedded systems that updates via OSTree images
+delivered via [Uptane](https://uptane.github.io/) and
+[aktualizr](https://github.com/uptane/aktualizr/).
 
 ## Distribution build tools
 
@@ -82,9 +96,20 @@ which uses libostree.
 The [BuildStream](https://gitlab.com/BuildStream/buildstream) build and
 integration tool supports importing and exporting from libostree repos.
 
+[fedora-iot/otto](https://github.com/fedora-iot/otto) is a tool that helps
+ship ostree commits inside Docker/OCI containers and run a webserver
+to serve the commits.
+
 Fedora [coreos-assembler](https://github.com/coreos/coreos-assembler) is
 the build tool used to generate Fedora CoreOS derivatives.
 
+[debos](https://github.com/go-debos/debos) is a tool-chain for simplifying the
+process of building a Debian-based OS image.
+
+[gardenlinux/ostree-image-builder](https://github.com/gardenlinux/ostree-image-builder)
+is a sample for building Debian-based OS images.
+It is not production ready but it might be useful to get started.
+
 ## Projects linking to libostree
 
 [rpm-ostree](https://github.com/projectatomic/rpm-ostree) is used by the
@@ -97,12 +122,17 @@ model for image and package systems.
 [eos-updater](https://github.com/endlessm/eos-updater) is a daemon that implements updates
 on EndlessOS.
 
-[flatpak](https://github.com/flatpak/flatpak) uses libostree for desktop
-application containers. Unlike most of the other systems here, flatpak does not
+[Flatpak](https://github.com/flatpak/flatpak) uses libostree for desktop
+application containers. Unlike most of the other systems here, Flatpak does not
 use the "libostree host system" aspects (e.g. bootloader management), just the
-"git-like hardlink dedup". For example, flatpak supports a per-user OSTree
+"git-like hardlink dedup". For example, Flatpak supports a per-user OSTree
 repository.
 
+[aktualizr](https://github.com/uptane/aktualizr/) is an
+[Uptane](https://uptane.github.io/)-conformant software update client library
+intended for use in automotive and other security-sensitive embedded devices.
+It uses OSTree to manage the OS of the host device by default.
+
 ## Language bindings
 
 libostree is accessible via [GObject Introspection](https://gi.readthedocs.io/en/latest/);
@@ -116,7 +146,7 @@ write higher level manual bindings on top; this is more common
 for statically compiled languages.  Here's a list of such bindings:
 
  - [ostree-go](https://github.com/ostreedev/ostree-go/)
- - [ostree-rs](https://github.com/ostreedev/ostree/tree/main/rust-bindings)
+ - [ostree-rs](./rust-bindings)
 
 ## Building
 
@@ -128,7 +158,7 @@ However, in order to build from a git clone, you must update the
 submodules.  If you're packaging OSTree and want a tarball, I
 recommend using a "recursive git archive" script.  There are several
 available online;
-[this code](https://github.com/ostreedev/ostree/blob/main/packaging/Makefile.dist-packaging#L11)
+[this code](https://github.com/ostreedev/ostree/blob/main/ci/Makefile.dist-packaging#L18)
 in OSTree is an example.
 
 Once you have a git clone or recursive archive, building is the
@@ -150,6 +180,11 @@ The libostree API documentation is available in [Reference](reference/).
 
 The ostree manual pages are available in [Manual](man/).
 
+## Contact and discussion forums
+
+There is also an `#ostree` channel on [Libera.Chat](ircs://irc.libera.chat/ostree) as
+well as [enabled Github discussions](https://github.com/ostreedev/ostree/discussions/).
+
 ## Contributing
 
 See [Contributing]({{ site.baseurl }}{% link CONTRIBUTING.md %}).

docs/introduction.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 20
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # OSTree Overview
 {: .no_toc }
@@ -186,6 +187,3 @@ Finally, each deployment has its own writable copy of the
 configuration store `/etc`.  On upgrade, OSTree will
 perform a basic 3-way diff, and apply any local changes to the
 new copy, while leaving the old untouched.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/related-projects.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 110
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Related Projects
 {: .no_toc }
@@ -388,6 +389,3 @@ as the tool abstracts the handling of OSTree concepts from the final users.
 [Torizon Cloud](https://developer.toradex.com/torizon/torizon-platform/torizon-platform-services-overview/)
 is a hosted OTA update system that provides OS updates to Torizon OS using
 OSTree and Aktualizr.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/repo.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 30
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Anatomy of an OSTree repository
 {: .no_toc }
@@ -183,6 +184,3 @@ the only way to provide GPG signatures (transitively) on deltas.
 If a repository administrator creates a summary file, they must
 thereafter run `ostree summary -u` to update it whenever a ref is
 updated or a static delta is generated.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/repository-management.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 100
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # Managing content in OSTree repositories
 {: .no_toc }
@@ -268,6 +269,3 @@ $ ostree --repo=/path/to/repo summary -u
 ```
 
 After that, clients fetching that commit will prefer fetching the "scratch" delta if they don't have the original ref.
-
-###### Licensing for this document:
-`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`

docs/var.md

@@ -1,6 +1,7 @@
 ---
 nav_order: 70
 ---
+<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
 
 # OSTree and /var handling