Project: Vector (Observability and Analysis / Observability)
File: DOCUMENTING.md

Documentation is very important to the Vector project! This document covers the process of documenting Vector from a contributor's perspective. All Vector contributors are for maintaining Vector's documentation in tandem with code changes. <!-- MarkdownTOC autolink="true" style="ordered" indent=" " --> 1. 3. 1. 5. 1. 2. <!-- /MarkdownTOC --> As a Vector contributor you are responsible for coupling the following user experience related changes with your code: Reference docs changes located in the (generally configuration changes) Existing guide changes located in the If relevant, your change for future release notes By default, you are not responsible for: Writing new guides related to your change (unless assigned) Writing a blog post on your change (unless assigned) Vector's serves as a referential index for all things Vector. For example, it contains a available in Vector's configuration. It's very data-centric and, as a result, is driven by structured data defined in the directory. is a declarative configuration language suitable for complex data definitions. Cue can be from package managers, however it may be necessary to install it from source in order to use the correct version that Vector depends on. Currently Vector is using `v0.7.0`. Using a CUE version different than this may result in CUE check/build errors. We are aiming to improve the developer experience around external tool dependencies (). Much of Vector's reference documentation is automatically compiled from source code (e.g., doc comments). To regenerate this content, run: ```bash make generate-component-docs ``` Vector has some CUE-related CI checks that are run whenever changes are made to the `docs` directory. This includes checks to make sure that the CUE sources are properly formatted. To run CUE's autoformatting, first , then run this command from the `vector` root: ```bash cue fmt ./website//*.cue ``` If that rewrites any files, make sure to commit your changes or else you'll see CI failures. In addition to proper formatting, the CUE sources need to be valid, that is, the provided data needs to conform to various CUE schemas. To check the validity of the CUE sources: ```bash make check-docs ``` A good practice for writing CUE is to make small, incremental changes and to frequently check to ensure that those changes are valid. If you introduce larger changes that introduce multiple errors, you may have difficulty interpreting CUE's verbose (and not always super helpful) log output. In fact, we recommend using a tool like to validate the sources every time you save a change: ```bash watchexec "make check-docs" ``` Contributors do not need to maintain a changelog. This is automatically generated via the `make release` command, made possible by the use of titles. Because Vector releases often contain many different changes, we use highlights to surface high-value, meaningful changes. Highlights are markdown files located in the that thoughtfully describe a feature. Each highlight is prominently displayed in the relevant . It should offer meaningful value to users. This is inherently subjective, and it is impossible to define exact rules for this distinction. But we should be cautious not to dilute the meaning of a highlight by producing low values highlights. Typically, a release contains no more than 6 highlights. Highlights are not blog posts. They are short one, maybe two, paragraph announcements. Highlights should allude to, or link to, a blog post if relevant. For example, is noteworthy, but also deserves an in-depth blog post covering the work that resulted in the performance and reliability benefit.