update contributing guideline

Signed-off-by: Gaurav Gahlot <[email protected]>

CONTRIBUTING.md

@@ -1,35 +1,167 @@
-## 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.
+  - 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.
 
-### How to Submit Change Requests
+### Get help
 
-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.
+Do reach out on Slack or Twitter and we are happy to help.
 
-### How to Report a Bug
+  - Drop by the [Slack channel](https://eqix-metal-community.slack.com).
+  - Say "Hi!" on [Twitter](https://twitter.com/tinkerbell_oss).
 
-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).
+## Contributing
 
-## Code Style Guides
+### 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 Guides
 
 #### 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
+```
+
+