Merge pull request #686 from replicatedhq/design-principles

Add Design Principles to the design folder

Author: chris-sanders

CONTRIBUTING.md

@@ -3,15 +3,20 @@
 Thank you for your interest in Troubleshoot, we welcome your participation. Please familiarize yourself with our [Code of Conduct](https://github.com/replicatedhq/troubleshoot/blob/master/CODE_OF_CONDUCT.md) prior to contributing. There are a number of ways to participate in Troubleshoot as outlined below:
 
 ## Issues
+
 - [Request a New Feature](https://github.com/replicatedhq/troubleshoot/issues/new?assignees=&labels=feature&template=feature_enhancement.md) Create an issue to add functionality that addresses a problem or adds an enhancement.  
-- [Report a Bug](https://github.com/replicatedhq/troubleshoot/issues/new?assignees=&labels=bug&template=bug_report.md) Report a problem or unexpected behaviour with Troubleshoot. 
+- [Report a Bug](https://github.com/replicatedhq/troubleshoot/issues/new?assignees=&labels=bug&template=bug_report.md) Report a problem or unexpected behaviour with Troubleshoot.
+
+## Design Principles
+
+When implementing a new feature please review the [design principles](./design/design-principles.md) to help guide the approach.
 
 ## Development Environment
 
 To get started we recommend:
 
 1. Go (v1.17 or later)
-2. A Kubernetes cluster (we recommend https://k3d.io/. This requires Docker v20.10.5 or later)
+2. A Kubernetes cluster (we recommend <https://k3d.io/>. This requires Docker v20.10.5 or later)
 3. Fork and clone the repo to $GOPATH/src/github.com/replicatedhq/
 4. Run `make support-bundle preflight` to generate binaries
 5. Run `make run-troubleshoot` to generate a support bundle with the `sample-troubleshoot.yaml` in the root of the repo
@@ -50,3 +55,4 @@ This is a rough outline of how to prepare a contribution:
 A pull request should address a single issue, feature or bug. For example, lets say you've written code that fixes two issues. That's great! However, you should submit two small pull requests, one for each issue as opposed to combining them into a single larger pull request. In general the size of the pull request should be kept small in order to make it easy for a reviewer to understand, and to minimize risks from integrating many changes at the same time. For example, if you are working on a large feature you should break it into several smaller PRs by implementing the feature as changes to several packages and submitting a separate pull request for each one.
 
 Code submitted in pull requests must be properly documented, formatted and tested in order to be approved and merged. The following guidelines describe the things a reviewer will look for when they evaluate your pull request. Here's a tip. If your reviewer doesn't understand what the code is doing, they won't approve the pull request. Strive to make code clear and well documented. If possible, request a reviewer that has some context on the PR.
+

design/design-principles.md

@@ -0,0 +1,27 @@
+# Troubleshoot Design Principles
+
+This document captures design principles that the Troubleshoot project abides by. This is intended to provide new contributors with guidance on how to approach problems and a better understanding of what to consider and address while implementing features.
+
+## Client not Cluster based
+
+Troubleshoot has to communicate with the Kubernetes API server to gather information. However, Troubleshoot should interact with the cluster as little as reasonably possible and has no intention of having a persistent in-cluster presence. There are several reasons for this approach, in no particular order those include:
+
+* Users experiencing an issue in their cluster may discover Troubleshoot after they have a problem and requiring installed components may exclude them from solving their problem.
+* A user may have limited cluster access and requiring cluster wide installation like a CRD or Operator can prevent them for using tools to recover from their errors.
+* By definition Troubleshoot is being used because there is an issue with the cluster, to prevent exasperating the issue Troubleshoot should avoid writing to the cluster.
+
+## Tools not specs
+
+The Troubleshoot project should include tools which can be used to diagnose issues but is not attempting to include Specs built into the project itself. The number of issues and projects which could benefit from Troubleshoot is very large and we intended to enable those projects to better support their project. It is unreasonable and undesirable for Troubleshoot to be the source of truth for all possible cluster and software issues.
+
+## Fail forward
+
+Clusters with issues can be unpredictable, the scope of error conditions is likely unbounded. Troubleshoot should keep this in mind when doing error handling and fail forward proceeding with as much of the intended operation as possible while logging the errors. For example if a collector fails to collect information that should not prevent other collectors from running. Any condition that causes Troubleshoot to hang or not complete a run is considered a bug.
+
+## Provide a predictable user experience
+
+When things go wrong people can be stressed and stressed people aren't likely to thoroughly read documentation. Whenever possible default values, command line flags, etc should be set to provide a user the best experience possible with the input provided. Some examples of this include:
+
+* When accepting flags for things like Namespaces, as much as possible, use the same syntax that `kubectl` accepts which users are likely to try instinctively.
+* Default to gathering more information not less, rarely is it easier to diagnose an issue with less information.
+