Add development principles (#56)

This commit is contained in:
Ahmet Alp Balkan 2018-09-30 16:49:08 -07:00 committed by GitHub
parent be65dd1fcd
commit 34f8fb18aa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 50 additions and 0 deletions

View file

@ -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

View file

@ -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.