FAQ: Link to building.md and enhance it

Now that the source is on GH we can say so! While we're here let's enhance the building docs.
c4rt0 · Nov 12, 2020 · 9dc1c95 · 9dc1c95
1 parent dbdba3c
commit 9dc1c95
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 8 deletions.
diff --git a/docs/building.md b/docs/building.md
@@ -1,6 +1,32 @@
-# Building RHCOS
+# Background
 
-You need to create a `rhcos.repo` file that looks like this:
+RHCOS is a derivative of both RHEL and Fedora CoreOS.  The tool
+to build both RHCOS and FCOS is [coreos-assembler](https://github.com/coreos/coreos-assembler/).
+See the upstream documentation there first, and pull down
+the container.
+
+coreos-assembler (or "cosa") accepts a configuration git repository
+as input.  This repository is that configuration for RHCOS,
+just like [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config)
+is for FCOS.
+
+For example, you would use
+```
+$ cosa init https://github.com/openshift/os
+```
+
+to start.  However, currently you need to configure
+the rpm-md repositories manually:
+
+# Repositories
+
+The RHEL repositories are only available to Red Hat customers,
+and it's likely that you want to use a mirror.  And further,
+a common scenario is to inject specific versioned rpm-md repositories
+to test different snapshots or "composes".  For these reasons,
+you need to provide the repos of input RPMs.
+
+To do so, create a `rhcos.repo` file that looks like this:
 
 ```
 # RHEL repos

diff --git a/docs/faq.md b/docs/faq.md
@@ -141,12 +141,7 @@ that are fixed in newer versions of the package.
 
 ## Q: How do I build my own version of RHCOS for testing?
 
-You need the RHCOS manifest configuration (currently hosted on an RHT internal [GitLab repo](https://url.corp.redhat.com/rhcos-repo)) and
-[coreos-assembler](https://github.com/coreos/coreos-assembler).
-
-If you want to replace particular binaries or RPMs in RHCOS, the `coreos-assembler` has
-[override mechanisms](https://github.com/coreos/coreos-assembler/blob/master/README-devel.md#using-overrides)
-to do this.
+See [building.md](building.md).
 
 Also reference the docs from the `machine-config-operator` about
 [hacking on the `machine-os-content`](https://github.com/openshift/machine-config-operator/blob/master/docs/HACKING.md#hacking-on-machine-os-content)