Moving docs over

ADOPTERS.md

@@ -0,0 +1,42 @@
+
+> **Note**
+> Do you want to add yourself to this list? Simply fork the repository and open a PR with the required change.
+> We have a short description of the adopter types at the bottom of this page. Each type is in alphabetical order. 
+
+# bootc Adopters (direct)
+
+| Type | Name | Since | Website | Use-Case |
+|:-|:-|:-|:-|:-|
+Vendor | Red Hat | 2024 | https://redhat.com | Image Based Linux 
+Vendor | HeliumOS | 2024 | https://www.heliumos.org/ | An atomic desktop operating system for your devices
+Vendor | AlmaLinux (Atomic SIG) | 2025 | [atomic-desktop](https://github.com/AlmaLinux/atomic-desktop), [atomic-workstation](https://github.com/AlmaLinux/atomic-workstation) | Atomic AlmaLinux desktop respins
+Vendor | Caligra | 2025 | [workbench](https://caligra.com/workbench/) | An OS designed to accelerate knowledge work
+Vendor | CIQ | 2026 | https://ciq.com | Rocky Linux from CIQ (RLC) - Image Based Linux - Standard and Cloud variants
+Vendor | Universal Blue (Aurora/Bazzite/Bluefin) | 2024 | https://universal-blue.org/ |  The reliability of a Chromebook, but with the flexibility and power of a traditional Linux desktop
+
+# bootc Adopters (indirect, via ostree)
+
+Bootc is a relatively new project, but much of the underlying technology and goals is *not* new.
+The underlying ostree project is over 13 years old (as of 2024). This project also relates
+to [rpm-ostree](https://github.com/coreos/rpm-ostree/) which has existed a really long time.
+
+Not every one of these projects uses bootc directly today, but a toplevel goal of bootc
+is to be the successor to ostree, and it is our aim to seamlessly carry forward these users.
+
+| Type | Name | Since | Website | Use-Case |
+|:-|:-|:-|:-|:-|
+| Vendor | Endless | 2014 | [link](https://www.endlessos.org/os) | A Completely Free, User-Friendly Operating System Packed with Educational Tools, Games, and More
+| Vendor | Red Hat | 2015 | [link](https://redhat.com) | Image Based Linux
+| Vendor | Apertis | 2020 | [link](https://apertis.org) | Collaborative OS platform for products
+| Vendor | Fedora Project | 2021 | [link](https://fedoraproject.org/atomic-desktops/) | An atomic desktop operating system aimed at good support for container-focused workflows
+| Vendor | Playtron GameOS | 2022 | [link](https://www.playtron.one/) | A video game console OS that has integration with the top PC game stores |
+| Vendor | Fyra Labs | 2024 | [link](https://fyralabs.com) | Bootc powers an experimental variant of Ultramarine Linux
+
+### Adopter Types
+
+**End-user**: The organization runs bootc in production in some way.
+
+**Integration**: The organization has a product that integrates with bootc, but does not contain bootc.
+
+**Vendor**: The organization packages bootc in their product and sells it as part of their product.
+

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+# Bootc Project Code of Conduct
+
+The Bootc project has adopted the [CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
+All community members, contributors, and participants in the Bootc project are expected to abide by this Code of Conduct. This includes respectful treatment of everyone, regardless of their background or identity.

CONTRIBUTING.md

@@ -0,0 +1,338 @@
+# Contributing to bootc
+
+Thanks for your interest in contributing!  At the current time,
+bootc is implemented in Rust, and calls out to important components
+which are written in Go (e.g. https://github.com/containers/image)
+as well as C (e.g. https://github.com/ostreedev/ostree/).  Depending
+on what area you want to work on, you'll need to be familiar with
+the relevant language.
+
+## Note: Before writing a big patch
+
+If you plan to contribute a large change, please get in touch *before*
+submitting a pull request by e.g. filing an issue describing your proposed
+change. This will help ensure alignment.
+
+## Development environment
+
+There isn't a single approach to working on bootc; however
+the primary developers tend to use Linux host systems,
+and test in Linux VMs.  One specifically recommended
+approach is to use [toolbox](https://github.com/containers/toolbox/)
+to create a containerized development environment
+(it's possible, though not necessary to create the toolbox
+ dev environment using a bootc image as well).
+
+At the current time most upstream developers use a Fedora derivative
+as a base, and the [hack/Containerfile](hack/Containerfile) defaults
+to Fedora.  However, bootc itself is not intended to strongly tie to a particular
+OS or distribution, and patches to handle others are gratefully
+accepted!
+
+## Key recommended ingredients:
+
+- A development environment (toolbox or a host) with a Rust and C compiler, etc.
+  While this isn't specific to bootc, you will find the experience of working on Rust
+  is greatly aided with use of e.g. [rust-analyzer](https://github.com/rust-lang/rust-analyzer/).
+- Install [bcvk](https://github.com/bootc-dev/bcvk).
+
+## Ensure you're familiar with a bootc system
+
+Worth stating: before you start diving into the code you should understand using
+the system as a user and how it works.  See the user documentation for that.
+
+## The Justfile
+
+The [Justfile](Justfile) is the primary interface for building and testing bootc.
+
+```bash
+just --list           # Show all targets organized by group
+just list-variants    # Show available build variants and current config
+```
+
+### Building from source
+
+Edit the source code; a simple thing to do is add e.g.
+`eprintln!("hello world");` into `run_from_opt` in [crates/lib/src/cli.rs](crates/lib/src/cli.rs).
+You can run `make` or `cargo build` to build that locally. However, a key
+next step is to get that binary into a bootc container image.
+
+Running `just` defaults to `just build` which will build a container
+from the current source code; the result will be named `localhost/bootc`.
+
+### Running an interactive shell in an environment from the container
+
+You can of course `podman run --rm -ti localhost/bootc bash` to get a shell,
+and try running `bootc`.
+
+### Running container-oriented integration tests
+
+```bash
+just test-container
+```
+
+### Running (TMT) integration tests
+
+A common cycle here is you'll edit e.g. `deploy.rs` and want to run the
+tests that perform an upgrade:
+
+```bash
+just test-tmt local-upgrade-reboot
+```
+
+To run a specific test:
+
+```bash
+just test-tmt readonly
+```
+
+### Faster iteration cycles
+
+The test cycle currently builds a disk image and creates a new ephemeral
+VM for each test run.
+
+You can shortcut some iteration cycles by having a more persistent
+environment where you run bootc.
+
+#### Upgrading from the container image
+
+One good approach is to create a persistent target virtual machine via e.g.
+`bcvk libvirt run` (or a cloud VM), and then after doing a `just build` and getting
+a container image, you can directly upgrade to that image.
+
+For the local case, check out [cstor-dist](https://github.com/cgwalters/cstor-dist).
+Another alternative is mounting via virtiofs (see e.g. [this PR to bcvk](https://github.com/bootc-dev/bcvk/pull/16)).
+If you're using libvirt, see [this document](https://libvirt.org/kbase/virtiofs.html).
+
+#### Using sysext for fast iteration
+
+For the fastest development cycle when working on the bootc client
+(e.g. `bootc upgrade`, `bootc switch`), you can use the sysext-based
+workflow. This builds the bootc binary via a container, shares it into
+a persistent VM via virtiofs, and overlays it onto `/usr` using
+systemd-sysext (~30s rebuild cycle):
+
+```bash
+# Build sysext and launch a persistent dev VM
+just bcvk up
+
+# After editing code, rebuild and refresh the overlay (~30s)
+just bcvk sync
+
+# SSH into the VM — bootc is your dev build
+just bcvk ssh bootc status
+
+# When done
+just bcvk down
+```
+
+The sysext overlay means `bootc` on the VM's PATH is your dev build.
+Run `just bcvk` to list all available commands.
+
+#### Running bootc against a live environment
+
+If your development environment host is also a bootc system (e.g. a
+workstation or a virtual server) one way to shortcut some cycles is just
+to directly run the output of the built binary against your host.
+
+Say for example your host is a Fedora 42 workstation (based on bootc),
+then you can `cargo b --release` directly in a Fedora 42 container
+or even on your host system, and then directly run e.g. `./target/release/bootc upgrade`
+etc.
+
+### Building and testing with the composefs backend
+
+bootc has two storage backends: `ostree` (default, production) and `composefs`
+(experimental). The composefs backend has several axes of configuration:
+
+| Variable | Values | Notes |
+|---|---|---|
+| `variant` | `ostree`, `composefs` | Storage backend |
+| `bootloader` | `grub`, `systemd` | systemd-boot required for UKI |
+| `boot_type` | `bls`, `uki` | UKI embeds the composefs digest |
+| `seal_state` | `unsealed`, `sealed` | Sealed signs the UKI for Secure Boot |
+| `filesystem` | `ext4`, `btrfs`, `xfs` | xfs lacks fsverity, incompatible with sealed |
+
+These are controlled via `BOOTC_`-prefixed environment variables.
+Using environment variables (rather than `just` command-line overrides)
+is recommended because they persist across commands in the same shell
+session — so `just build` followed by `just test-tmt` will use the
+same configuration:
+
+```bash
+# Set up a composefs development session
+export BOOTC_variant=composefs
+export BOOTC_bootloader=systemd
+# Now all just targets use these settings:
+just build
+just test-tmt readonly
+just test-container
+```
+
+The constraints are:
+
+- `sealed` requires `boot_type=uki` (the digest lives in the UKI cmdline)
+- `sealed` requires `filesystem` with fsverity support (`ext4` or `btrfs`)
+- `uki` requires `bootloader=systemd`
+
+Common workflows:
+
+```bash
+# Simplest composefs build (unsealed, grub, BLS, ext4)
+export BOOTC_variant=composefs
+just build
+
+# Composefs with systemd-boot
+export BOOTC_variant=composefs BOOTC_bootloader=systemd
+just build
+
+# Fully sealed image (systemd-boot + signed UKI + Secure Boot)
+# This is the most common composefs dev workflow:
+just build-sealed
+
+# Run composefs integration tests (all four params are required)
+just test-composefs systemd ext4 bls unsealed
+
+# Run sealed UKI tests
+just test-composefs systemd ext4 uki sealed
+
+# Validate composefs digests match between build and install views
+# (useful for debugging mtime/metadata issues)
+just validate-composefs-digest
+```
+
+The `build-sealed` target generates test Secure Boot keys in
+`target/test-secureboot/` and builds a complete sealed image with all
+the sealed composefs settings. See
+[experimental-composefs.md](docs/src/experimental-composefs.md) for
+more information on sealed images.
+
+
+### Debugging via lldb
+
+The `hack/lldb` directory contains an example of how to use lldb to debug bootc code.
+`hack/lldb/deploy.sh` can be used to build and deploy a bootc VM in libvirt with an lldb-server
+running as a systemd service. Depending on your editor, you can then connect to the lldb server
+to use an interactive debugger, and set up the editor to build and push the new binary to the VM.
+`hack/lldb/dap-example-vim.lua` is an example for neovim.
+
+The VM can be connected to via `ssh test@bootc-lldb` if you have [nss](https://libvirt.org/nss.html)
+enabled.
+
+For some bootc install commands, it's simpler to run the lldb-server in a container, e.g.
+
+```bash
+sudo podman run --pid=host --network=host --privileged --security-opt label=type:unconfined_t -v /var/lib/containers:/var/lib/containers -v /dev:/dev -v .:/output localhost/bootc-lldb lldb-server platform --listen "*:1234" --server
+```
+
+## Code linting
+
+The `make validate` target runs checks locally that we gate on
+in CI, currently around `cargo fmt` and `cargo clippy`.
+
+## Running the tests
+
+First, you can run many unit tests with `cargo test`.
+
+### container tests
+
+There's a small set of tests which are designed to run inside a bootc container
+and are built into the default container image:
+
+```
+$ just test-container
+```
+
+## Submitting a patch
+
+The podman project has some [generic useful guidance](https://github.com/containers/podman/blob/main/CONTRIBUTING.md#submitting-pull-requests);
+like that project, a "Developer Certificate of Origin" is required.
+
+### Sign your PRs
+
+The sign-off is a line at the end of the explanation for the patch. Your
+signature certifies that you wrote the patch or otherwise have the right to pass
+it on as an open-source patch. The rules are simple: if you can certify
+the below (from [developercertificate.org](https://developercertificate.org/)):
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+San Francisco, CA 94110 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+Then you just add a line to every git commit message:
+
+    Signed-off-by: Joe Smith <joe.smith@email.com>
+
+Use your real name (sorry, no pseudonyms or anonymous contributions.)
+
+If you set your `user.name` and `user.email` git configs, you can sign your
+commit automatically with `git commit -s`.
+
+### Git commit style
+
+Please look at `git log` and match the commit log style, which is very
+similar to the
+[Linux kernel](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git).
+
+You may use `Signed-off-by`, but we're not requiring it.
+
+**General Commit Message Guidelines**:
+
+1. Title
+    - Specify the context or category of the changes e.g. `lib` for library changes, `docs` for document changes, `bin/<command-name>` for command changes, etc.
+    - Begin the title with the first letter of the first word capitalized.
+    - Aim for less than 50 characters, otherwise 72 characters max.
+    - Do not end the title with a period.
+    - Use an [imperative tone](https://en.wikipedia.org/wiki/Imperative_mood).
+2. Body
+    - Separate the body with a blank line after the title.
+    - Begin a paragraph with the first letter of the first word capitalized.
+    - Each paragraph should be formatted within 72 characters.
+    - Content should be about what was changed and why this change was made.
+    - If your commit fixes an issue, the commit message should end with `Closes: #<number>`.
+
+Commit Message example:
+
+```bash
+<context>: Less than 50 characters for subject title
+
+A paragraph of the body should be within 72 characters.
+
+This paragraph is also less than 72 characters.
+```
+
+For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)