docs: Introduce spec overview and template (#14839)
This commit is contained in:
parent
3b133ed05b
commit
9f9ab54be7
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue