Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Document the Crossplane project file (and the new pre-built function and per-language schema options)

Open
  • Is something wrong?
#1,106 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
65/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Domain
cli, documentation

Research direction

Start with the CLI command reference and the Configurations packaging docs, then account for the versioned CLI documentation restructuring in crossplane/docs#1104. Done means a project-file reference covers ProjectSpec, Directory and Tarball functions, and per-language schema generation, with examples and links to the affected workflows.

Written by the indexing model from the issue text.

Description

content request
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, which documents command flags but not the project file's schema. The packaging docs (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 (<pathPrefix>-<arch>.tar/.tar.gz), so projects can build functions with their own toolchain (make, Nix, Bazel, ko, docker save, etc.).

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.

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.

Dominant language
SCSS
Stars
60
Forks
163
Avg merge
5d 6h
Merged PRs (30d)
1

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from crossplane/docs

All issues in crossplane/docs

Similar issues

More CLI issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.