Merge pull request #884 from LalatenduMohanty/glossary_doc_883

docs: add glossary and bootstrap-vs-build docs

Author: LalatenduMohanty

docs/concepts/bootstrap-vs-build.rst

@@ -0,0 +1,109 @@
+Bootstrap vs Build
+==================
+
+Fromager has two distinct modes of operation: **bootstrap** and **build**.
+Understanding the difference is key to using fromager effectively.
+
+.. seealso::
+
+   :doc:`/using` covers practical command usage and examples.
+
+Quick Comparison
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Aspect
+     - Bootstrap
+     - Build
+   * - **Scope**
+     - Entire dependency tree
+     - Single package
+   * - **Purpose**
+     - Discover and resolve all dependencies
+     - Compile source into wheel
+   * - **Recursion**
+     - Yes (processes dependencies)
+     - No (one package only)
+   * - **Input**
+     - Requirements file or package specs
+     - Package name + version + source URL
+   * - **Output**
+     - Dependency graph, build order, all wheels
+     - One wheel file
+
+Bootstrap Mode
+--------------
+
+The ``bootstrap`` command recursively discovers and builds all dependencies:
+
+.. code-block:: text
+
+   fromager bootstrap numpy
+     ├── Resolve version → numpy==1.26.0
+     ├── Download source
+     ├── Extract build dependencies from pyproject.toml
+     ├── bootstrap(setuptools)  ← Process build dependencies first
+     ├── Build wheel (with build deps available)
+     ├── Extract install dependencies from wheel metadata
+     └── bootstrap(cython)  ← Process each install dependency
+           └── Resolve version → cython==3.0.0, then repeat...
+
+**Key operations:**
+
+1. Version resolution for all packages
+2. Dependency graph construction
+3. Build order determination
+4. Wheel building (for each discovered package)
+
+**When to use:** Initial discovery of what needs to be built, creating a complete
+wheel collection from scratch.
+
+Build Mode
+----------
+
+The ``build`` command compiles a single package without recursion:
+
+.. code-block:: text
+
+   fromager build numpy 1.26.0 https://pypi.org/simple/
+     ├── Download sdist
+     ├── Apply patches
+     ├── Create build environment
+     ├── Run pip wheel
+     └── Output: numpy-1.26.0-cp311-linux_x86_64.whl
+
+**Key operations:**
+
+1. Source download and preparation
+2. Build environment setup
+3. Wheel compilation
+4. No dependency discovery or recursion
+
+**When to use:** Production builds where the build order is already known
+(from a previous bootstrap), CI/CD pipelines, rebuilding individual packages.
+
+Relationship
+------------
+
+While ``bootstrap`` and ``build`` share some common steps (downloading sources,
+applying patches, running pip wheel), they are separate implementations optimized
+for different use cases. Bootstrap maintains state across the entire dependency tree,
+while build operates statelessly on a single package.
+
+The ``build-sequence`` and ``build-parallel`` commands bridge these modes by reading
+a ``build-order.json`` file (produced by bootstrap) and invoking the build logic
+for each package in the specified order.
+
+Typical Workflow
+----------------
+
+1. **Development:** Use ``bootstrap`` to discover all dependencies and create
+   initial wheel collection
+
+2. **Production:** Use ``build-sequence`` or ``build-parallel`` with the
+   ``build-order.json`` from bootstrap to rebuild deterministically
+
+3. **Fixes:** Use ``build`` to rebuild individual packages after applying patches

docs/concepts/index.rst

@@ -4,4 +4,5 @@ Concepts
 .. toctree::
    :maxdepth: 1
 
+   bootstrap-vs-build
    dependencies