diff --git a/docs/specs/README.md b/docs/specs/README.md new file mode 100644 index 000000000..8c5940516 --- /dev/null +++ b/docs/specs/README.md @@ -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. diff --git a/docs/specs/template.md b/docs/specs/template.md new file mode 100644 index 000000000..ed69d7ab0 --- /dev/null +++ b/docs/specs/template.md @@ -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