diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index 99faef3fd..000000000 --- a/DESIGN.md +++ /dev/null @@ -1,174 +0,0 @@ -![zero](https://github.com/commitdev/zero/blob/master/docs/img/logo-small.png?raw=true) - -# Design - -**In this document `zero` is a placeholder for some named utility.** - -The guiding principle behind `zero` is to **make it easy for developers to ship -to production on day 1** - -## Developer Experience (DX) - -Developer Experience is the equivalent of User Experience when the primary user -of the product is a developer. DX cares about the developer experience of using -a product, its libs, SDKs, documentation, frameworks, open-source solutions, -general tools, APIs, etc. - -**DX Pillars** - -- Function: Something is only as useful as it is functional. If it doesn't work - it's of no value. Maintaining function is a key element of quality and - percetpion of quality. -- Stability: Performance and reliability -- Ease of Use: The tool alone only forms one part of the developers journey. - Resoures like github issues, documentation, clear workflows, snippets, etc - all help reduce the friction in using and learning a new tool. -- Clarity: Clear, concise, actionable information makes the world of difference - when using a tool. - -## DX Guidelines - -- easy onboarding. it must be easy for someone to get started with the tool, - and to join an existing \$setup or create a new one. -- follows [principle of least astonishment][1] -- use short easy to remember commands -- help commands on [every sub command][2] -- pipe-able / machine-readable output -- feedback at the end of a command. every tool and command is guiding someone - down a path and we should tell them where to go next. for example, a command - that results in some build artifact; tell them the typical next step. github - does the same thing with their post remote push message telling you to open a - PR. any command that takes a long time to run should let the user know though - some kind of visual feedback. for scripts, this feedback should be able to be - suppressed, like curl silent mode. -- colors; when do we use them? anything needs to work _without_ colors too, so - they can't be the primary way of labeling / indicating anything. just an - enhancement to words or symbols that are already on the screen. For an - example of things to think about [see this mocha issue][3] - -## Implementation Principles - -- Discoverable: -- Familiar: -- Alterable: -- Parsable: -- Consistency: as a command line tool we need to establish a convention and - stick to it. things like `[cmd] [noun] [verb]` with flags. consistent flag options, - etc. short form flags are possible but we should encourage long form flags - when scripting usage of the tool so that things are more self-documenting. -- error messages should be easy to understand and steer someone towards an - answer / next step. -- error early: if we can detect things that will be problems do it as early as - possible before proceeding with an operation. it makes no sense to take - expensive actions that may mutate state which will only half-finish -- idempotency - -## Users - -- Our users are not power users -- typically experienced but not devops masters -- havent built their own full environment before or they have but are missing - best practices / some clear conventions. -- Users will more often be joining a team or a project much more frequently - than creating an environment from scratch. That only happens one time. - -## Installation - -- must be easy to install for users of different platforms with the least - amount of lift - linux, osx. should look at mechanisms for installation like brew, apt, curl -- dont have to worry about windows for now but we shouldn't back ourselves into - a corner - -## Documentation - -Documentation should be consistent, easy to follow, and follow the user through -their own journey. We should only make use of commonly installed utilities which -come with the prerequisites we define or commands we _know_ are installed. For -example use `psql` vs `pgcli` in shell examples. - -Each README should have an outline on: - -- what the tool does -- which dependencies to install -- how to install the application -- how to contribute -- communication channels - -To ensure the README is easy to read, please keep length limited. Any FAQ -sections or hints / tips / design decisions / etc should go into a separate -documentation path. - -Shell commands should be preceeded with a `$` dollar sign to act as a visual -representation of the shell. While the world will be moving towards `zsh` we -should use compatible examples whenever possible. Shell commands should wrap at -the 80 character limit. For long commands use a `\` to move additional arguments -or flags onto separate lines, and omit the preceeding `$` so that it can be -copy-pasted without the dollar sign affecting interpretation. - -```shell -$ zero arg \ - --flag-one \ - --flag-two \ - three -``` - -## Concepts - -#### Help - -built in help should follow standard conventions. `[option]` with square -brackets. `` which are required with greater-than and lesser-than -signs. - -```shell -$ zero --help -$ zero noun [[]noun] verb --help -$ zero noun verb [options] --help -$ -$ Usage: noun verb [options] -$ # flags list -``` - -or - -```shell -$ zero -``` - -## Glossary - -Terms we'll use repeatedly should have clear definitions or use common knowledge -definitions. Some of these terms may still require definitions. Any frequently -used word should be added to this list if it applies to usage in `zero`. - -- **Project**: A project is the top level (root) entity that contains the infrastructure and configuration. A project is compartmentalized and has no awareness of the details of other projects. Environments are built using Modules as part of a project. - -- **Module**: This is a git repository that contains everything Zero needs to set up a piece of a project. - - What’s included in a single Module? - - Templates - - Documentation - - Potentially definition of something to execute (terraform, api calls, etc) - - Examples of Current modules: - - Zero-aws-eks-stack - - Zero-deployable-backend - - Zero-deployable-react-frontend - -- Application all the pieces of your project working together (Frontend, Service, Infrastructure). - -- **Infrastructure**: The systems your application runs on and other required dependencies that are not part of the Frontends or Services. Typically provided by a cloud provider and provisioned with Terraform. (For example AWS EKS, RDS, Cloudfront, etc.) - -- **Environment**: A running instance of your entire Application. Examples being Dev / Staging / UAT / Production (one or many set up for a single project) - -- **Frontend**: A single page app serving the front-end of a web application. Typically makes requests to a Service. - -- **Service**: A backend app serving APIs or providing funtionality for a web application. Typically serves requests from the Frontend App. - -- **Pipeline**: CI/CD pipeline responsible for running automated tests and deploying Frontend Apps and/or Services to Environments. - - - - -[1]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment -[2]: https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-help.html -[3]: https://github.com/mochajs/mocha/issues/802 diff --git a/README.md b/README.md index 392e3d3c2..dc7cb2361 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -![zero](https://raw.githubusercontent.com/commitdev/zero/main/docs/img/logo-small.png) +

+ +

## What is Zero @@ -6,6 +8,7 @@ Zero is an open source tool which makes it quick and easy for startup technical Zero sets up everything you need so you can immediately start building your product. +Zero was created by [Commit](https://commit.dev). ## Why is Zero good for startups As a technical founder or the first technical hire at a startup, your sole focus is to build the logic for your application and get it into customers’ hands as quickly and reliably as possible. Yet you immediately face multiple hurdles before even writing the first line of code. You’re forced to make many tech trade-offs, leading to decision fatigue. You waste countless hours building boilerplate SaaS features not adding direct value to your customers. You spend precious time picking up unfamiliar tech, make wrong choices that result in costly refactoring or rebuilding in the future, and are unaware of tools and best practices that would speed up your product iteration. diff --git a/docs/img/logo-small.png b/docs/img/logo-small.png index 0d1c1e0d2..0b789a830 100644 Binary files a/docs/img/logo-small.png and b/docs/img/logo-small.png differ diff --git a/docs/img/logo.png b/docs/img/logo.png index 3314b1dbd..0b789a830 100644 Binary files a/docs/img/logo.png and b/docs/img/logo.png differ