RFC: Design in the open (#1055)

* rfc: first draft of RFC0001

* add placeholder for PR

* update PR link

* Update docs/rfcs/0001-designing-in-the-open.md

Co-authored-by: Robert Lankford <[email protected]>

* Update docs/rfcs/0001-designing-in-the-open.md

Co-authored-by: Robert Lankford <[email protected]>

* clarify "designing in the open" is best-effort

* update 0001

* fix dead link in production/README.md

* add recommended sections for RFC proposals

* describe the process for approving a proposal

* ignore RFC template in link checker

* Update docs/rfcs/0001-designing-in-the-open.md

Co-authored-by: Richard Hartmann <[email protected]>

* Update docs/rfcs/0001-designing-in-the-open.md

Co-authored-by: Richard Hartmann <[email protected]>

* do my nitty 80-char line length limit change

* indent pros/cons to a single section

* document process for superseding RFCs

* remove RFC mutability requirement

* add extra flavor around not recommending google docs

* require Google Doc -> RFC conversion

* move new files

Co-authored-by: Robert Lankford <[email protected]>
Co-authored-by: Richard Hartmann <[email protected]>

.github/workflows/markdown.links.config.json

@@ -1,5 +1,8 @@
 {
   "ignorePatterns": [
+    {
+      "pattern": "^https://github.com/grafana/agent/pull/XXXX$"
+    },
     {
       "pattern": "^http://prometheus.k3d.localhost:30080"
     },

.github/workflows/publish.yml

@@ -5,7 +5,7 @@ on:
     branches:
     - main
     paths:
-    - 'docs/**'
+    - 'docs/user/**'
 
 jobs:
   sync:
@@ -21,7 +21,7 @@ jobs:
         branch: master
         host: github.com
         github_pat: '${{ secrets.GH_BOT_ACCESS_TOKEN }}'
-        source_folder: docs
+        source_folder: docs/user
         target_folder: content/docs/agent/latest
     - shell: bash
       run: |

docs/README.md

@@ -1,21 +1,10 @@
-+++
-draft = "True"
-+++
+# Grafana Agent Documentation
 
-<p align="center"><img src="assets/logo_and_name.png" alt="Grafana Agent logo"></p>
+This directory contains documentation for Grafana Agent. It is split into two
+parts:
 
-Grafana Agent is an telemetry collector for sending metrics, logs,
-and trace data to the opinionated Grafana observability stack. It works best
-with:
-
-* [Grafana Cloud](https://grafana.com/products/cloud/)
-* [Grafana Enterprise Stack](https://grafana.com/products/enterprise/)
-* OSS deployments of [Grafana Loki](https://grafana.com/oss/loki/), [Prometheus](https://prometheus.io/), [Cortex](https://cortexmetrics.io/), and [Grafana Tempo](https://grafana.com/oss/tempo/)
-
-
-- Grafana Agent uses less memory on average than Prometheus – by doing less
-  (only focusing on `remote_write`-related functionality).
-- Grafana Agent allows for deploying multiple instances of the Agent in a
-  cluster and only scraping metrics from targets that are running on the same host.
-  This allows for distributing memory requirements across the cluster
-  rather than pressurizing a single node.
+* `user/`: Documentation for users. This directory is hosted on
+  [grafana.com/docs/agent](https://grafana.com/docs/agent/latest/) and we
+  recommend interacting with it there instead of viewing the markdown on
+  Github.
+* `rfcs/`: RFCs for proposals relating to Grafana Agent.

docs/rfcs/0000-template.md

@@ -0,0 +1,5 @@
+# Title
+
+* Date: YYYY-MM-DD
+* Author: Full Name (@github_username)
+* PR: [grafana/agent#XXXX](https://github.com/grafana/agent/pull/XXXX)

docs/rfcs/0001-designing-in-the-open.md

@@ -0,0 +1,141 @@
+# Designing in the Open
+
+* Date: 2021-11-02
+* Author: Robert Fratto (@rfratto)
+* PR: [grafana/agent#1055](https://github.com/grafana/agent/pull/1055)
+
+## Summary
+
+Many open source projects start behind closed doors, where it's designed,
+prototyped, and tested before being released publicly. This can be true
+regardless of why the project is being made; even personal side projects likely
+start by someone designing alone.
+
+Meanwhile, many open source projects might want to create a community of
+developers. Much of the beauty of succesful open source projects originates
+from the varied backgrounds of its contributors: different people with
+different use cases combining together to make a widely useful piece of
+software.
+
+However, even with an intent to foster a community of developers, it's natural
+to accidentally build a habit from the closed-door design process. Even when
+once-private proposals are made public, potential external contributors can
+find themselves simply as spectators:
+
+* Initial design is gated to core maintainers, in particular if they all work
+  for the same company. This leaves less room for new people to help out.
+* New concerns are less impactful if the proposal already receieved core
+  maintainer consensus.
+* Historical proposals with context and discussions become hard to find.
+
+I believe it takes a deliberate inversion of process to foster community
+participation. This document proposes how Grafana Agent will utilize public
+spaces for its primary home for future design proposals.
+
+## Goals
+
+* Outline options for proposing changes to Grafana Agent
+* Lower the barrier to entry for interested parties to become maintainers
+
+## Non-Goals
+
+* Enforce that every change originates from a fully public proposal or
+  discussion. While all maintainers and contributors will be encouraged to
+  design openly, there may be legal, security, privacy, or business reasons
+  that prevent some or all context from being made public.
+
+* Be overly prescriptive: too many rules can hinder adoption of a process. This
+  document outlines intention, not hard policy.
+
+## Proposal
+
+Public proposals may take one of two forms:
+
+* Issue proposals
+* RFC PR proposals (e.g., this document)
+
+### Issues
+
+Issues are the quickest path towards proposing a change. Issue proposals must
+be opened at the [grafana/agent issues page](https://github.com/grafana/agent/issues).
+
+There are no strict set of rules for issue-based proposals, but authors are
+recommended to prefix the issue title with `Proposal:` so it may be found more
+easily.
+
+### RFC PRs
+
+RFC PR proposals must at least:
+
+* Be placed in the `docs/rfcs` folder of the `grafana/agent` repository
+* Have a lowercase filename in hyphen-case with an `.md` extension
+* Prefix the filename with the RFC ID
+  * ID `xxxx` may be initially used until the final ID is known
+* Contain valid markdown
+* Start with the title of the proposal
+* Contain a bullet point list of metadata of:
+  * The date the proposal was written
+  * The list of authors, with their names and GitHub usernames
+  * The PR where the proposal was posted
+
+`0000-template.md` contains a template to use for writing proposals that
+conforms to these rules.
+
+The remainder of the proposal may be formatted however the author wishes. Some
+example sections in the RFC may be:
+
+* Summary: What is the background that lead to this proposal?
+* Goals: What are the main goals of the proposal?
+* Non-Goals: What _aren't_ the main goals of the proposal?
+* Proposal: What is the proposal?
+* Pros/Cons:
+  * Pros: What are the upsides to this proposal?
+  * Cons: What are the downsides to this proposal?
+* Considered Alternatives: Why is this proposal the best path forward? What
+  were the alternatives?
+* Open Questions: What questions still need to be answered?
+* Prior Art: What was this proposal based on, if anything?
+
+#### RFC Review
+
+RFCs should be opened as a PR to grafana/agent, ideally prefixed in the PR
+title with `RFC:` to easily identify it amongst other PRs.
+
+### Google Docs Proposals
+
+Google Docs may be useful for early feedback rounds during a proposal. However,
+it is not recommended for the permanent home of a proposal:
+
+* Change and comment history may not be available to all viewers.
+
+* The file owner may delete the proposal, leading to a gap in historical
+  context.
+
+Google Docs proposals will be permitted if linked to from an issue proposal.
+Google Doc proposals must be converted into an RFC proposal prior to formally
+accepting the proposal. Enforcing this ensures that historical context is
+recorded, though it is still not ideal as it discards comment history.
+
+## Accepting Proposals
+
+All readers are encouraged to engage in reviewing proposals. However, whether a
+proposal is accepted is determined by [rough consensus][] of the Grafana Agent
+governance team. External contributors may eventually be invited to [join the
+governance team][governance] if they have a history of making ongoing
+contributions to the project or community.
+
+## Considered alternatives
+
+A few existing public proposal processes have been examined for inspiration:
+
+* [IETF's RFCs](https://www.ietf.org/standards/rfcs/)
+* [Rust's RFCs](https://github.com/rust-lang/rfcs)
+* [Joyent's Requests for Discussions](https://github.com/joyent/rfd)
+* [OpenTelemetry's OTEPs](https://github.com/open-telemetry/oteps)
+* [Kubernetes Enhancement Proposals (KEPs)](https://github.com/kubernetes/enhancements)
+
+All of these processes are similar, but in the end, the current objective is to
+start collecting proposals publicly rather than to be prescriptive yet.
+
+[rough consensus]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#technical-decisions
+[governance]: https://github.com/grafana/agent/blob/main/GOVERNANCE.md#team-members

docs/user/README.md

@@ -0,0 +1,21 @@
++++
+draft = "True"
++++
+
+<p align="center"><img src="assets/logo_and_name.png" alt="Grafana Agent logo"></p>
+
+Grafana Agent is an telemetry collector for sending metrics, logs,
+and trace data to the opinionated Grafana observability stack. It works best
+with:
+
+* [Grafana Cloud](https://grafana.com/products/cloud/)
+* [Grafana Enterprise Stack](https://grafana.com/products/enterprise/)
+* OSS deployments of [Grafana Loki](https://grafana.com/oss/loki/), [Prometheus](https://prometheus.io/), [Cortex](https://cortexmetrics.io/), and [Grafana Tempo](https://grafana.com/oss/tempo/)
+
+
+- Grafana Agent uses less memory on average than Prometheus – by doing less
+  (only focusing on `remote_write`-related functionality).
+- Grafana Agent allows for deploying multiple instances of the Agent in a
+  cluster and only scraping metrics from targets that are running on the same host.
+  This allows for distributing memory requirements across the cluster
+  rather than pressurizing a single node.

production/README.md

@@ -13,7 +13,7 @@ Here are some resources to help you run the Grafana Agent:
 
 ## Windows Installation
 
-To run the Windows Installation, download the Windows Installer executable from the [release page](https://github.com/grafana/agent/releases). Then run the installer, this will setup the Agent and run the Agent as a Windows Service. More details can be found in the [Windows Guide](../docs/getting-started/install-agent-on-windows.md)
+To run the Windows Installation, download the Windows Installer executable from the [release page](https://github.com/grafana/agent/releases). Then run the installer, this will setup the Agent and run the Agent as a Windows Service. More details can be found in the [Windows Guide](https://grafana.com/docs/agent/latest/getting-started/install-agent-on-windows/)
 
 ## Running the Agent with Docker