Update documentation

CONTRIBUTING.md

@@ -1,35 +1,166 @@
-## Hello Contributors!
+# Hello Contributors!
 
-Thx for your interest!
-We're so glad you're here.
+Thanks for helping make Tinkerbell better 😍!
 
-### Important Resources
+There are many areas we can use contributions - ranging from code, documentation, feature proposals, issue triage, samples, and content creation.
 
-#### bugs: [https://github.com/tinkerbell/tink/issues](https://github.com/tinkerbell/tink/issues)
+First, please read the [code of conduct](CODE_OF_CONDUCT.md).
+By participating, you're expected to uphold this code.
 
-### Code of Conduct
+## Table of Contents
 
-Available via [https://github.com/tinkerbell/tink/blob/master/.github/CODE_OF_CONDUCT.md](https://github.com/tinkerbell/tink/blob/master/.github/CODE_OF_CONDUCT.md)
+-   [Choose something to work on](#choose-something-to-work-on)
+    -   [Get help](#get-help)
+-   [Contributing](#contributing)
+    -   [File an issue](#file-an-issue)
+    -   [Submit a change](#submit-a-change)
+    -   [Code style guide](#code-style-guide)
+-   [Understanding code structure](#understanding-code-structure)
+    -   [cmd](#cmd)
+    -   [db](#db)
+    -   [deploy](#deploy)
+    -   [grpc-server](#grpc-server)
+    -   [protos](#protos)
 
-### Environment Details
+## Choose something to work on
 
-[https://github.com/tinkerbell/tink/blob/master/Makefile](https://github.com/tinkerbell/tink/blob/master/Makefile)
+There are [multiple repositories](https://github.com/tinkerbell) within the Tinkerbell organization.
+Each repository has beginner-friendly issues that are a great place to get started on your contributor journey.
+For example, a list of issues for Tink repository can be found [here](https://github.com/tinkerbell/tink/issues).
+If there is something that you find interesting and would like to work on, go ahead.
+You can filter issues with label "[good first issue](https://github.com/tinkerbell/tink/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)", which are relatively self sufficient issues and great for first time contributors.
 
-### How to Submit Change Requests
+-   If you are going to pick up an issue, it would be good to add a comment stating the intention.
+-   If the contribution is a big change/new feature, please raise an issue and discuss the needs, design in the issue in detail.
 
-Please submit change requests and / or features via [Issues](https://github.com/tinkerbell/tink/issues).
-There's no guarantee it'll be changed, but you never know until you try.
-We'll try to add comments as soon as possible, though.
+### Get help
 
-### How to Report a Bug
+Do reach out on Slack or Twitter and we are happy to help.
 
-Bugs are problems in code, in the functionality of an application or in its UI design; you can submit them through [Issues](https://github.com/tinkerbell/tink/issues).
+-   Drop by the [Slack channel](https://eqix-metal-community.slack.com).
+-   Say "Hi!" on [Twitter](https://twitter.com/tinkerbell_oss).
 
-## Code Style Guides
+## Contributing
+
+### File an issue
+
+Not ready to contribute code, but see something that needs work?
+While the community encourages everyone to contribute code, it is also appreciated when someone reports an issue.
+Issues should be filed under the appropriate Tinkerbell subrepository.
+For example, a documentation issue should be opened in [tinkerbell/tinkerbell-docs](https://github.com/tinkerbell/tinkerbell-docs/issues).
+Make sure to adhere to the prompted submission guidelines while opening an issue.
+
+### Submit a change
+
+All submissions are more than welcome.
+There are [multiple repositories](https://github.com/tinkerbell) within the Tinkerbell organization.
+Before you submit a change, you must fork the repository and submit a pull request with the change(s).
+Please ensure that you adhere to the prompted submission guidelines while raising a pull request.
+We will try to review and provide feedback as soon as possible.
+
+### Code Style Guide
 
 #### Protobuf
 
 Please ensure protobuf related files are generated along with _any_ change to a protobuf file.
 CI will enforce this, but its best to commit the generated files along with the protobuf changes in the same commit.
 Handling of protobuf deps and generating the go files are both handled by the [protoc.sh](./protos/protoc.sh) script.
-Both go & protoc are required by protoc.sh, these are both installed and used if using nix-shell.
+Both `go`, and `protoc` are required by `protoc.sh`.
+These are both installed and used if using `nix-shell`.
+
+#### Unit Tests
+
+One must support their proposed changes with unit tests.
+As you submit a pull request(PR) the CI generates a code coverage report.
+It will help you identify parts of the code that are not yet covered in unit tests.
+
+## Understanding code structure
+
+This is a nonexhaustive list important packages that happen to cover most of the code base.
+
+### cmd
+
+The `cmd` package is home for three core binaries for Tinkerbell:
+
+-   `tink-cli` - the CLI for interacting with the `tink-server`
+-   `tink-server` - the tink API server
+-   `tink-worker` - responsible for executing the workload
+
+```
+.
+├── cmd
+│   ├── tink-cli
+│   │   └── cmd
+│   │       ├── delete
+│   │       ├── get
+│   │       ├── hardware
+│   │       ├── template
+│   │       └── workflow
+│   ├── tink-server
+│   └── tink-worker
+│       ├── cmd
+│       └── internal
+```
+
+### db
+
+The `db` holds everything you need to deal with the database.
+We use [PostgreSQL](https://www.postgresql.org/) as the data store.
+The package contains database migrations, and an API to interact with database.
+
+```
+.
+├── db
+│   ├── migration
+│   ├── mock
+│   └── testdata
+```
+
+### deploy
+
+The `deploy` directory contains all the essentials to setup Tinkerbell stack.
+You can setup a local stack with `docker-compose` or Vagrant.
+
+```
+.
+├── deploy
+│   ├── db
+│   ├── registry
+│   ├── tls
+│   └── vagrant
+│       └── scripts
+```
+
+### grpc-server
+
+The `grpc-server` exposes a gRPC API that connects everything together.
+It has a base server that implements the API.
+
+```
+.
+├── grpc-server
+│   ├── grpc_server.go
+│   ├── hardware.go
+│   ├── hardware_test.go
+│   ├── template.go
+│   ├── template_test.go
+│   ├── tinkerbell.go
+│   ├── tinkerbell_test.go
+│   ├── workflow.go
+│   └── workflow_test.go
+```
+
+### protos
+
+The `protos` package contains all the protobuf files used by the gRPC server.
+Handling of protobuf deps and generating the go files are both handled by the [protoc.sh](./protos/protoc.sh) script.
+Also, both `go`, and `protoc` are required by `protoc.sh`.
+
+```
+.
+├── protos
+│   ├── hardware
+│   ├── packet
+│   ├── template
+│   └── workflow
+```

README.md

@@ -7,34 +7,56 @@
 
 This repository is [Experimental](https://github.com/packethost/standards/blob/master/experimental-statement.md) meaning that it's based on untested ideas or techniques and not yet established or finalized or involves a radically new and innovative style! This means that support is best effort (at best!) and we strongly encourage you to NOT use this in production.
 
-It is comprised of following five major components:
+## What's Powering Tinkerbell?
 
-1.  A DHCP server ([boots](https://github.com/tinkerbell/boots))
-2.  A workflow engine (tink, this repository)
-3.  A metadata service ([hegel](https://github.com/tinkerbell/hegel))
-4.  An in-memory installation environment([osie](https://github.com/tinkerbell/osie))
-5.  A controller/handler of BMC interactions([pbnj](https://github.com/tinkerbell/pbnj))
+The Tinkerbell stack consists of several microservices, and a gRPC API:
 
-The workflow engine is comprised of a server and a CLI, which communicates over gRPC.
-The CLI is used to create a workflow and its building blocks: templates and targeted hardware.
+### Tink
+
+[Tink][1] is the short-hand name for the tink-server, tink-worker, and tink-cli.
+`tink-worker` and `tink-server` communicate over gRPC, and are responsible for processing workflows.
+The CLI is the user-interactive piece for creating workflows and their building blocks, templates and hardware data.
+
+### Boots
+
+[Boots][2] is Tinkerbell's DHCP server.
+It handles DHCP requests, hands out IPs, and serves up iPXE.
+It uses the Tinkerbell client to pull and push hardware data.
+It only responds to a predefined set of MAC addresses so it can be deployed in an existing network without interfering with existing DHCP infrastructure.
+
+### Hegel
+
+[Hegel][3] is the metadata service used by Tinkerbell and OSIE.
+It collects data from both and transforms it into a JSON format to be consumed as metadata.
+
+### OSIE
+
+[OSIE][4] is Tinkerbell's default an in-memory installation environment for bare metal.
+It installs operating systems and handles deprovisioning.
+
+### Hook
+
+[Hook][5] is the newly introduced alternative to OSIE.
+It's the next iteration of the in-memory installation environment to handle operating system installation and deprovisioning.
+
+### PBnJ
+
+[PBnJ][6] is an optional microservice that can communicate with baseboard management controllers (BMCs) to control power and boot settings.
 
 ## Building
 
-Use `make help` Luke.
+Use `make help`.
 The most interesting targets are `make all` (or just `make`) and `make images`.
 `make all` builds all the binaries for your host OS and CPU to enable running directly.
 `make images` will build all the binaries for Linux/x86_64 and build docker images with them.
 
-## Workflow
-
-A workflow is a framework responsible for handling flexible, bare metal provisioning, that is...
-
--   standalone and does not need the Packet API to function
--   contains `Boots`, `Tink`, `Hegel`, `OSIE`, `PBnJ` and workers
--   can bootstrap any remote worker using `Boots + Hegel + OSIE + PBnJ`
--   can run any set of actions as Docker container runtimes
--   receive, manipulate, and save runtime data
-
 ## Website
 
 For complete documentation, please visit the Tinkerbell project hosted at [tinkerbell.org](https://tinkerbell.org).
+
+[1]: https://github.com/tinkerbell/tink
+[2]: https://github.com/tinkerbell/boots
+[3]: https://github.com/tinkerbell/hegel
+[4]: https://github.com/tinkerbell/osie
+[5]: https://github.com/tinkerbell/hook
+[6]: https://github.com/tinkerbell/pbnj