From 34f8fb18aa3a72c63e5c43780f27bc8ed1ad9748 Mon Sep 17 00:00:00 2001 From: Ahmet Alp Balkan Date: Sun, 30 Sep 2018 16:49:08 -0700 Subject: [PATCH] Add development principles (#56) --- CONTRIBUTING.md | 6 +++++ docs/development-principles.md | 44 ++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 docs/development-principles.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 939e534..1dce611 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,12 @@ We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. +## Development Principles (for Googlers) + +There are a few principles for developing or refactoring the service +implementations. Read the [Development Principles +Guide](./docs/development-principles.md). + ## Contributor License Agreement Contributions to this project must be accompanied by a Contributor License diff --git a/docs/development-principles.md b/docs/development-principles.md new file mode 100644 index 0000000..0deae0c --- /dev/null +++ b/docs/development-principles.md @@ -0,0 +1,44 @@ +# Development Principles + +> **Note:** This document outlines guidances behind some development decisions +> behind the Hipster Shop demo application. + +### Minimal configuration + +Running the demo locally or on GCP should not require minimal to no +configuration unless absolutely necessary to run critical parts of the demo. + +Configuration that takes multiple steps, especially such as creating service +accounts should be avoided. + +### App must work well outside GCP + +Demo application should work reasonably well when it is not deployed to GCP +services. The experience of running the application locally or on GCP should +be close. + +For example: +- OpenCensus prints the traces to stdout when it cannot connect to GCP. +- Stackdriver Debugging tries connecting to GCP multiple times, eventually gives + up. + +### Running on GCP must not reduce functionality + +Running the demo on the GCP must not reduce/lose any of the capabilities +developers have when running locally. + +For example: Logs should still be printed to stdout/stderr even though logs are +uploaded to Stackdriver Logging when on GCP, so that developers can use "kubectl +logs" to diagnose each container. + +### Microservice implementations should not be complex + +Each service should provide a minimal implementation and try to avoid +unnecessary code and logic that's not executed. + +Keep in mind that any service implementation is a decent example of “a GRPC +application that runs on Kubernetes”. Keeping the source code short and +navigable will serve this purpose. + +It is okay to have intentional inefficiencies in the code as they help +illustrate the capabilities of profiling and diagnostics offerings.