Document the Crossplane project file (and the new pre-built function and per-language schema options)
- Dominant language
- SCSS
- Stars
- 60
- Forks
- 163
- Avg merge
- 15h 20m
- Merged PRs (30d)
- 9
Description
### What's Missing?
The Crossplane CLI's project workflow (`crossplane project init`/`build`/`run`) is configured by a project file — a `Project` resource whose `spec` (`ProjectSpec`) controls the repository, dependencies, paths, target architectures, embedded functions, and schema generation. Today this file has no prose documentation. The only place any of it surfaces is the auto-generated [CLI command reference](https://docs.crossplane.io/master/cli/command-reference/), which documents command flags but not the project file's schema. The packaging docs ([Configurations](https://docs.crossplane.io/master/packages/configurations/)) only cover the older `crossplane xpkg build` + `crossplane.yaml` flow, not the newer Projects flow.
crossplane/cli#24 just merged and adds two new optional `ProjectSpec` fields that need documenting:
**1. Pre-built function runtimes** (`spec.functions`) — fixes crossplane/cli#21. An explicit list of functions to build, which disables the default per-subdirectory auto-discovery. Each entry uses a `source` discriminator (`Directory` or `Tarball`). `Tarball` sources skip language detection and load a pre-built single-platform OCI image tarball per target architecture (`-.tar`/`.tar.gz`), so projects can build functions with their own toolchain (make, Nix, Bazel, `ko`, `docker save`, etc.).
```yaml
spec:
architectures: [amd64, arm64]
functions:
- source: Directory
directory:
name: function-a
- source: Tarball
tarball:
name: function-b
pathPrefix: build/function-b
```
**2. Per-language schema generation** (`spec.schemas.languages`) — fixes crossplane/cli#29. Restricts schema generation to a subset of the supported languages (Go, JSON, KCL, Python) instead of generating all four. Applies to both the project's own XRDs and its dependencies, and flows through `project build`/`run` and `dependency update-cache`/`clean-cache`.
```yaml
spec:
schemas:
languages: [python]
```
Ideally these are documented as part of a broader project-file reference page rather than in isolation, since the project file itself is currently undocumented.
Note the CLI docs are mid-restructure (crossplane/docs#1104 moves them into their own versioned tree and gives them a separate sidebar/version menu), so placement should account for that.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.