vdk: update contributing and readme

CONTRIBUTING.md

@@ -7,15 +7,19 @@ For any questions about the CLA process, please refer to our [FAQ](https://cla.v
 # Structure of the project
 
 * projects - the interesting part, aka the source code - there is a separate folder for each component.
-  * vdk-control-service - Java spring-based API for managing jobs, job deployments, and executions in Kubernetes.
-  * vdk-sdk - Python-based SDK containing data library for data jobs development and CLI for managing data jobs.
+  * vdk-control-service - Java spring-based API for managing lifecyhle of data jobs: job definitions, job deployments, and executions in Kubernetes.
+  * vdk-core - Python-based SDK containing data library for developing and running data jobs. Includes a powerful plugin framework .
+  * vdk-heartbeat - tool for verifying deployed SDK and Control Service are functional and working correctly
+  * vdk-control-cli - User friendly CLI interface over Control Service operations.
   * plugins - Set of plugins that we maintain and provide for different use-cases like lineage, database support, ...
 * support - helper scripts used by developers of the project during their workday
+* cicd - build and ci cd related scripts common across all projects.
+* examples - list of example use-cases. Each example directory has its README with detailed explanations
 
 # How to build, debug
 
-Each subproject has its own README.md with details on how to test (locally), build it, and run it.
-If in doubt, open the .gitlab-ci.yml file.
+Each project has its own README.md with details on how to test (locally), build it, and run it.
+If in doubt, open the .gitlab-ci.yml file of the project.
 Read through the Gitlab CI file to find the build process confirmed to work by an automated continuous integration (CI).
 CI runs in Docker Linux containers, so if you have docker installed, you will be able to replicate the process.
 All components have "build.sh" scripts in the cicd/ folder that would build the whole component.
@@ -29,7 +33,7 @@ Before suggesting a change/feature, think if this change only serves your needs,
 that is good for the project itself because it helps multiple users.
 
 For more complex features/changes, submitting your design is valuable, if possible, before you even write a single line of code.
-We do not have a formal process but creating a PR in Github with your proposal as markdown is recommended. 
+Creating a PR in Github with your proposal as markdown (in [specs](specs) directory) is recommended. 
 Reviews and feedback will happen on the PR.
 
 Also, reach out to the community - through slack, mail to discuss your idea. We are happy to help.

README.md

@@ -5,32 +5,28 @@ Versatile Data Kit is a data engineering framework that enables Data Engineers t
 
 # About Versatile Data Kit
 
-The abstraction of the common data engineering problems, provided by Versatile Data Kit, accelerates development of data applications and helps to manage data applications, making sure they are packaged, versioned and deployed correctly. Tracking both code and data modifications and relations between them enables engineers to troubleshoot more quickly and provides easy revert to a stable version
+Versatile Data Kit provides an abstraction layer that helps solve common data engineering problems.
+It can be called by the workflow engine with the goal to make data engineers more efficient
+(for example, it make sure data applications are packaged, versioned and deployed correctly,
+dealing with credentials, retries, reconnects, etc.).
+Everything exposed by Versatile Data Kit includes built-in monitoring, troubleshooting,
+and smart notifications capabilities.
+(for example, tracking both code and data modifications and relations between them
+enables engineers to troubleshoot more quickly and provides an easy revert to a stable version)
 
 Versatile Data Kit consists of:
 
-* Control Service which enables creating, deploying, managing and executing Data Jobs in Kubernetes runtime environment. It has multitenancy support, SSO, Access Control and auditing capabilities
-* Command line tool for data engineers to use locally to create by sample, deploy, list and manage Data Jobs in the Cloud
+* Control Service which enables creating, deploying, managing and executing Data Jobs in Kubernetes runtime environment.
+  It has multitenancy support, SSO, Access Control and auditing capabilities. It exposes CLI.
 * A development Kit to develop, test and run Data Jobs on your machine. It comes with common functionality for data ingestion and processing like: 
-    * sending data for ingestion from different sources to different destinations
-    * integrating raw table data into a dimensional model in Data Warehouse 
-    * Extremely extensible and adaptable to your organizations use-cases
-    * and many others
 
 
 # Installation and Getting Started
 
-#### Install Versatile Data Kit Control Service
-
-```bash
-helm repo add bitnami https://charts.bitnami.com/bitnami
-helm install bitnami/pipelines-control-service
-```
-
 #### Install Versatile Data Kit SDK
 
 ```bash
-pip install vdk
+pip install quickstart-vdk
 ```
 
 #### Use
@@ -39,11 +35,16 @@ pip install vdk
 # see Help to see what you can do
 vdk --help 
 # create a new job and start playing around.
-vdk create -u <URI-YOU-GOT-FROM-helm-install-OUTPUT>
+vdk create-sample-job
+vdk run first-job
 ```
 
+For more see [installation documentation](../versatile-data-kit.wiki/install.md)
+
 # Documentation
 
+Official documentation for Versatile Data Kit can be found [here](https://github.com/vmware/versatile-data-kit/wiki/Introductionw the [Code of Condu).
+
 # Contributing 
 
 If you are interested in contributing as a developer, visit [CONTRIBUTING.md](CONTRIBUTING.md).

support/git-commit-template.txt

@@ -18,9 +18,14 @@
 # what were the commands, what was the output, what was expected, details of your testing environment.
 
 # What type of change are you making?
-# Bug fix (non-breaking change which fixes an issue) or a cosmetic change/minor improvement - those do not need a design document
-# New feature (non-breaking change which adds functionality) - those generally are bigger changes - usually in multiple commits and often require design.
-# Breaking change (fix or feature that would cause existing functionality to change) - breaking changes are considered carefully and we try to find a way to solve the problem without those.
+# Bug fix (non-breaking change which fixes an issue) or a cosmetic change/minor improvement
+#       those generally do not need a design document, consider updating the CHANGELOG only if it's user facing bug.
+# New feature (non-breaking change which adds functionality)
+#       those generally are bigger changes - usually in multiple commits and often require design spec.
+#       Will usually require updating CHANGELOG.md
+# Breaking change (fix or feature that would cause existing functionality to change)
+#       breaking changes are considered carefully and we try to find a way to solve the problem without those.
+#       If necessary, they follow deprecation policy (see Dev Guide for more info)
 
-# All commits must be signed
+# All commits must be signed (contain Signed-off-by: Names (mail) - this is automatically done with git commit -s
 # See https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits