Skip to content

Commit

Permalink
docs: Introduce spec overview and template (#14839)
Browse files Browse the repository at this point in the history
  • Loading branch information
powersj authored Feb 22, 2024
1 parent 3b133ed commit 9f9ab54
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 0 deletions.
71 changes: 71 additions & 0 deletions docs/specs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Telegraf Specification Overview

## Objective

Define and layout the Telegraf specification process.

## Overview

The general goal of a spec is to detail the work that needs to get accomplished
for a new feature. A developer should be able to pick up a spec and have a
decent understanding of the objective, the steps required, and most of the
general design decisions.

The specs can then live in the Telegraf repository to share and involve the
community in the process of planning larger changes or new features. The specs
also serve as a public historical record for changes.

## Process

The general workflow is for a user to put up a PR with a spec outlining the
task, have any discussion in the PR, reach consensus, and ultimately commit
the finished spec to the repo.

While researching a new feature may involve an investment of time, writing the
spec should be relatively quick. It should not take hours of time.

## Spec naming

Please name the actual file prefixed with `tsd` and the next available
number, for example:

* tsd-001-agent-write-ahead-log.md
* tsd-002-inputs-apache-increase-timeout.md
* tsd-003-serializers-parquet.md

All lower-case and separated by hyphens.

## What belongs in a spec

A spec should involve the creation of a markdown file with at least an objective
and overview:

* Objective (required) - One sentence headline
* Overview (required) - Explain the reasoning for the new feature and any
historical information. Answer the why this is needed.

Please feel free to make a copy the template.md and start with that.

The user is free to add additional sections or parts in order to express and
convey a new feature. For example this might include:

* Keywords - Help identify what the spec is about
* Is/Is-not - Explicitly state what this change includes and does not include
* Prior Art - Point at existing or previous PRs, issues, or other works that
demonstrate the feature or need for it.
* Open Questions - Section with open questions that can get captured in
updates to the PR

## Changing existing specs

Small changes which are non-substantive, like grammar or formatting are gladly
accepted.

After a feature is complete it may make sense to come back and update a spec
based on the final result.

Other changes that make substantive changes are entirely up to the maintainers
whether the edits to an existing RFC will be accepted. In general, finished
specs should be considered complete and done, however, priorities, details, or
other situations may evolve over time and as such introduce the need to make
updates.
20 changes: 20 additions & 0 deletions docs/specs/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Title

## Objective

One sentence explanation of the feature.

## Overview

Background and details about the feature.

## Keywords

A few items to specify what areas of Telegraf this spec affects (e.g. outputs,
inputs, processors, aggregators, agent, packaging, etc.)

## Is/Is-not

## Prior art

## Open questions

0 comments on commit 9f9ab54

Please sign in to comment.