Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (99 loc) · 5.94 KB

CONTRIBUTING.md

File metadata and controls

129 lines (99 loc) · 5.94 KB

Contributing to the Crossplane CLI

Welcome to the Crossplane CLI, and thank you for your interest in contributing.

Please start by reading the Crossplane contributing document. The Crossplane CLI follows the same guidelines and policies as the core Crossplane project, including coding style. We also use a similar Nix-based development environment.

The CLI maintainers primarily communicate in the #sig-cli channel on Slack.

Topics specific to CLI development are covered below.

The Command Tree

The Crossplane CLI's command tree follows a noun-first structure. This means all top-level commands are nouns (cluster, composition, dependency) rather than verbs (get, list, generate). New commands should be added under the relevant noun, or a new noun if needed. Please feel free to ask on Slack or propose a new command in an issue if you aren't sure where a new command should go.

kong

We use kong as our CLI framework. Each command is defined as a struct, in which fields become subcommands, positional arguments, or flags. Kong's struct tags can be used to control many behaviors, including validation, auto-completion, and documentation.

Command Maturity Levels

We have three maturity levels for commands:

  • Generally Available (GA): Stable commands that will not be removed or have breaking changes made without considerable notice.
  • Beta: Commands that are relatively stable and unlikely to be removed, but may have breaking changes made in a subsequent minor version.
  • Alpha: Experimental commands that may change significantly or be removed at any time.

Alpha and beta commands are marked as such using a custom kong struct tag, maturity:"alpha" or maturity:"beta". These struct tags control two things:

  1. Alpha commands are hidden from the help output by default. Users must enable showing alpha commands in their CLI configuration file.
  2. Alpha and beta commands automatically have notes added to their help text indicating the maturity level and what it means.

If a command is not tagged with a maturity level, it will inherit from its parent in the command tree. This means that if you're introducing a whole tree of commands into beta, only the parent needs to be tagged. Commands without a maturity level anywhere in their tree are considered GA.

Note that in the past alpha and beta commands were put under separate command trees (crossplane alpha and crossplane beta). We have moved away from this scheme in order to help keep the command tree and codebase more stable as commands mature.

Embedded Documentation

The CLI is self-documenting. Short descriptions for commands and flags should be added using kong struct tags. Longer help should be returned by each command's Help() method. This help should be formatted using markdown, which we render in the console using the glamour library.

The crossplane generate-docs command is used to generate CLI reference documentation for docs.crossplane.io. Markdown returned by each command's Help() is embedded nearly verbatim into this documentation. Please observe the following guidelines in order to make the docs look as good as possible:

  • Don't put a top-level heading on your Markdown-formatted detailed help. An appropriate heading will be added automatically in both terminal usage and docs generation.
  • Use level 2 headings (##) and below for sections in your help text. These will render correctly in the terminal, and be adjusted as needed by the generate-docs command to ensure the documentation page is properly structured.
  • Use inline code and code blocks for commands, flags, arguments, etc. This looks good when rendered, and avoids spelling and grammar false positives.

If in doubt about whether your help will look good, you can easily check your work by generating the docs locally:

# Clone the docs repository.
git clone https://github.com/crossplane/docs.git
cd docs

# Generate the docs.
crossplane generate-docs -o content/master/cli/command-reference.md

# Build the docs and serve them locally for preview.
hugo serve

The vale Linter

The Crossplane documentation uses vale to enforce spelling and style guidelines. This repository includes a CI check that generates documentation and runs vale using the configuration from crossplane/docs to ensure that our generated documentation does not trigger any warnings or errors.

It is sometimes unavoidable to have help text that triggers vale warnings or errors. For example, the heading for the help section about the crossplane config command includes the word "config" outside a code block, causing vale to suggest that we replace it with "configuration". For these situations, it is possible to temporarily disable specific vale rules in two ways:

  1. If the problem is in detailed Markdown help, use vale Markdown comments.
  2. If the problem is in help generated by kong (command names, flag descriptions, etc.), use our custom novale:"..." kong tag. This will result in a Markdown comment of the form <!-- vale ... = NO --> being generated at the top of the relevant command's documentation section with a matching = YES comment at the bottom.

In both cases, please scope vale overrides as tightly as possible and ensure all rules are re-enabled after the problematic section. Prefer to disable specific matches rather than whole rules, and rules rather than whole styles.