add repo documentation (#67)

Signed-off-by: Ashutosh Kumar <[email protected]>
openebs-archive · May 15, 2020 · 4041d4e · 4041d4e
1 parent d4acf45
commit 4041d4e
Show file tree

Hide file tree

Showing 9 changed files with 1,354 additions and 1 deletion.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,3 @@
+## Community Code of Conduct
+
+This project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,17 @@
+# Contributing
+
+This [link](docs/developer-guide/start.md) contains all information about
+building cstor-operators from source, contribution guide, reaching out to
+contributors, maintainers etc.
+
+If you want to build the cstor-operators right away then the following is the step:
+
+#### You have a working [Go environment] and [Docker environment].
+
+```
+mkdir -p $GOPATH/src/k8s.io
+cd $GOPATH/src/k8s.io
+git clone https://github.com/openebs/cstor-operators
+cd cstor-operators
+make all.amd64
+```
diff --git a/README.md b/README.md
@@ -1,2 +1,82 @@
 # cstor-operators
-Collection of OpenEBS cStor Data Engine Operators
+[![Go](https://github.com/openebs/cstor-operators/workflows/Go/badge.svg)](https://github.com/openebs/cstor-operators/actions)
+[![Build Status](https://travis-ci.org/openebs/cstor-operators.svg?branch=master)](https://travis-ci.org/openebs/cstor-operators)
+[![Slack](https://img.shields.io/badge/JOIN-SLACK-blue)](https://openebs-community.slack.com)
+
+<img width="300" align="right" alt="OpenEBS Logo" src="https://raw.githubusercontent.com/cncf/artwork/master/projects/openebs/stacked/color/openebs-stacked-color.png" xmlns="http://www.w3.org/1999/html">
+
+Collection of OpenEBS cStor Data Engine Operators. The data engine operators
+are responsible for cStor pool and volume orchestration.
+
+
+## Project Status
+
+This project is under active development and is considered to be in beta state.
+
+The current implementation supports the following for cStor pools and volumes:
+1. Provisioning and De-provisioning of cStor pools.
+2. Pool expansion by adding disk.
+3. Disk replacement by removing a disk.
+4. Volume replica scale up and scale down.
+5. Volume resize.
+
+The data engine operators works in conjunction with the cStor CSI driver to finally
+provide a consumable volume for stateful workloads.
+
+For more details on cStor-CSI drivers, please refer [here](https://github.com/openebs/cstor-csi)
+
+Table of contents:
+==================
+- [Quickly deploy it on K8s and get started](docs/quick.md)
+- [Pool Operations Tutorial](docs/tutorial/intro.md)
+- [High level overview](#overview)
+- [Issues and PRs](#issues-and-prs)
+- [Contributing](#contributing)
+- [Code of conduct](#code-of-conduct)
+
+## Overview
+
+At a high-level, cstor operators consists of following components.
+- cspc-operator
+- pool-manager
+- cvc-operator
+- volume-manager
+
+An OpenEBS admin/user can use CSPC(CStorPoolCluster) API (YAML) to provision cStor pools in a Kubernetes cluster.
+As the name suggests, CSPC can be used to create a cluster of cStor pools across Kubernetes nodes.
+It is the job of **cspc-operator** to reconcile the CSPC obejct and provision CStorPoolInstance(s) as specified 
+in the CSPC. A cStor pool is provisioned on node by utilising the disks attached to the node and is represented by 
+CStorPoolInstance(CSPI) custom resource in a Kubernetes cluster. One has freedom to specify the disks that they
+want to use for pool provisioning.
+
+CSPC API comes with a variety of tunables and features and the API can be viewed for [here](https://github.com/openebs/api/blob/master/pkg/apis/cstor/v1/cstorpoolcluster.go)
+
+Once a CSPC is created, cspc-operator provision CSPI CR and **pool-manager** deployment on each nodes where cStor pool should 
+be created. The pool-manager deployment watches for its corresponding CSPI on the node and finally execute commands to
+perform pool operations e.g pool provisioning.
+
+**Note:** It is not recommended to modify the CSPI CR and pool-manager in the running cluster unless you know what you are 
+trying to do. CSPC should be the only point of interaction.
+
+## Issues And PRs
+We consider issues also as a part of contribution to the project.
+If you want to raise any issue for cstor-operators please do that at [openebs/openebs].
+We are tracking issues for all the OpenEBS components at the same place.
+If you are unsure about how to proceed, do not hesitate in communicating in 
+OpenEBS community slack [channel]. 
+
+See [contributing](#contributing) section to learn more about how to contribute to cstor-operators.
+
+
+## Contributing
+
+Please read the contributing guidelines [here](./CONTRIBUTING.md).
+
+## Code of conduct
+
+Pleae read the community code of conduct [here](./CODE_OF_CONDUCT.md).
+
+[Docker environment]: https://docs.docker.com/engine
+[Go environment]: https://golang.org/doc/install
+[openebs/openebs]: https://github.com/openebs/openebs
+[channel]: https://openebs-community.slack.com
diff --git a/docs/developer-guide/devel.md b/docs/developer-guide/devel.md
@@ -0,0 +1,171 @@
+# Development Workflow
+
+## Prerequisites
+
+* You have Go 1.13+ installed on your local host/development machine.
+* You have Docker installed on your local host/development machine. Docker is required for building cstor-operators component container images and to push them into a Kubernetes cluster for testing.
+
+## Initial Setup
+
+### Fork in the cloud
+
+1. Visit https://github.com/openebs/cstor-operators.
+2. Click `Fork` button (top right) to establish a cloud-based fork.
+
+### Clone fork to local host
+
+Place openebs/cstor-operators' code on your `GOPATH` using the following cloning procedure.
+Create your clone:
+
+```sh
+
+mkdir -p $GOPATH/src/github.com/openebs
+cd $GOPATH/src/github.com/openebs
+
+# Note: Here $user is your GitHub profile name
+git clone https://github.com/$user/cstor-operators.git
+
+# Configure remote upstream
+cd $GOPATH/src/github.com/openebs/cstor-operators
+git remote add upstream https://github.com/openebs/cstor-operators.git
+
+# Never push to upstream master
+git remote set-url --push upstream no_push
+
+# Confirm that your remotes make sense
+git remote -v
+```
+
+## Development
+
+### Always sync your local repository
+
+Open a terminal on your local host. Change directory to the cstor-operators-fork root.
+
+```sh
+$ cd $GOPATH/src/github.com/openebs/cstor-operators
+```
+
+ Checkout the master branch.
+
+ ```sh
+ $ git checkout master
+ Switched to branch 'master'
+ Your branch is up-to-date with 'origin/master'.
+ ```
+
+ Recall that origin/master is a branch on your remote GitHub repository.
+ Make sure you have the upstream remote openebs/cstor-operators by listing them.
+
+ ```sh
+ $ git remote -v
+ origin	https://github.com/$user/cstor-operators.git (fetch)
+ origin	https://github.com/$user/cstor-operators.git (push)
+ upstream	https://github.com/openebs/cstor-operators.git (fetch)
+ upstream	no_push (push)
+ ```
+
+ If the upstream is missing, add it by using below command.
+
+ ```sh
+ $ git remote add upstream https://github.com/openebs/cstor-operators.git
+ ```
+
+ Fetch all the changes from the upstream master branch.
+
+ ```sh
+ $ git fetch upstream master
+ remote: Counting objects: 141, done.
+ remote: Compressing objects: 100% (29/29), done.
+ remote: Total 141 (delta 52), reused 46 (delta 46), pack-reused 66
+ Receiving objects: 100% (141/141), 112.43 KiB | 0 bytes/s, done.
+ Resolving deltas: 100% (79/79), done.
+ From github.com:openebs/cstor-operators
+   * branch            master     -> FETCH_HEAD
+ ```
+
+ Rebase your local master with the upstream/master.
+
+ ```sh
+ $ git rebase upstream/master
+ First, rewinding head to replay your work on top of it...
+ Fast-forwarded master to upstream/master.
+ ```
+
+ This command applies all the commits from the upstream master to your local master.
+
+ Check the status of your local branch.
+
+ ```sh
+ $ git status
+ On branch master
+ Your branch is ahead of 'origin/master' by 38 commits.
+ (use "git push" to publish your local commits)
+ nothing to commit, working directory clean
+ ```
+
+ Your local repository now has all the changes from the upstream remote. You need to push the changes to your own remote fork which is origin master.
+
+ Push the rebased master to origin master.
+
+ ```sh
+ $ git push origin master
+ Username for 'https://github.com': $user
+ Password for 'https://[email protected]':
+ Counting objects: 223, done.
+ Compressing objects: 100% (38/38), done.
+ Writing objects: 100% (69/69), 8.76 KiB | 0 bytes/s, done.
+ Total 69 (delta 53), reused 47 (delta 31)
+ To https://github.com/$user/cstor-operators.git
+ 8e107a9..5035fa1  master -> master
+ ```
+
+### Create a new feature branch to work on your issue
+
+ Your branch name should have the format XX-descriptive where XX is the issue number you are working on followed by some descriptive text. For example:
+
+ ```sh
+ $ git checkout -b 1234-fix-developer-docs
+ Switched to a new branch '1234-fix-developer-docs'
+ ```
+
+
+### Test your changes
+After you are done with your changes, run the unit tests.
+ ```sh
+ cd $GOPATH/src/github.com/openebs/cstor-operators
+
+ # Run every unit test
+ make test
+ ```
+
+### Build the images
+You can build amd64 images by following command. 
+ ```sh
+ cd $GOPATH/src/github.com/openebs/cstor-operators
+ make all.amd64
+ ```
+
+
+### Keep your branch in sync
+
+[Rebasing](https://git-scm.com/docs/git-rebase) is very important to keep your branch in sync with the changes being made by others and to avoid huge merge conflicts while raising your Pull Requests. You will always have to rebase before raising the PR.
+
+```sh
+# While on your myfeature branch (see above)
+git fetch upstream
+git rebase upstream/master
+```
+
+While you rebase your changes, you must resolve any conflicts that might arise and build and test your changes using the above steps.
+
+## Submission
+
+### Create a pull request
+
+Before you raise the Pull Requests, ensure you have reviewed the checklist in the [CONTRIBUTING GUIDE](./start.md):
+- Ensure that you have re-based your changes with the upstream using the steps above.
+- Ensure that you have added the required unit tests for the bug fixes or new feature that you have introduced.
+- Ensure your commits history is clean with proper header and descriptions.
+
+Go to the [openebs/cstor-operators github](https://github.com/openebs/cstor-operators) and follow the Open Pull Request link to raise your PR from your development branch.
diff --git a/docs/developer-guide/start.md b/docs/developer-guide/start.md
@@ -0,0 +1,74 @@
+# cstor-operators developer guide
+
+Table of contents:
+==================
+- [Contributing to OpenEBS cstor-operators](#contributing-to-openebs-cstor-operators)
+- [Steps to contribute](#steps-to-contribute)
+- [Pull Request Checklist](#pull-request-checklist)
+- [Sign your work](#sign-your-work)
+- [Communicate](#communicate)
+
+# Contributing to OpenEBS cstor-operators
+
+OpenEBS uses the standard GitHub pull requests process to review and accept contributions.  There are several areas that could use your help. For starters, you could help in improving the sections in this document by either creating a new issue describing the improvement or submitting a pull request to this repository. The issues for the various OpenEBS components (including maya components) are maintained in [openebs/openebs](https://github.com/openebs/openebs/issues) repository.
+
+* If you are a first-time contributor, please see [Steps to Contribute](#steps-to-contribute).
+* If you have documentation improvement ideas, go ahead and create a pull request. See [Pull Request checklist](#pull-request-checklist).
+* If you would like to make code contributions, please start with [Setting up the Development Environment](#setting-up-your-development-environment).
+* If you would like to work on something more involved, please connect with the OpenEBS Contributors. ( See [communicate](#communicate) ) 
+
+## Steps to Contribute
+
+OpenEBS is an Apache 2.0 Licensed project and all your commits should be signed with Developer Certificate of Origin. See [Sign your work](#sign-your-work).
+
+* Find an issue to work on or create a new issue. The issues are maintained at [openebs/openebs](https://github.com/openebs/openebs/issues). You can pick up from a list of [good-first-issues](https://github.com/openebs/openebs/labels/good%20first%20issue).
+* Claim your issue by commenting your intent to work on it to avoid duplication of efforts.
+* Fork the repository on GitHub.
+* Create a branch from where you want to base your work (usually master).
+* Make your changes. If you are working on code contributions, please see [Setting up the Development Environment](#setting-up-your-development-environment).
+* Relevant coding style guidelines are the [Go Code Review Comments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments) and the _Formatting and style_ section of Peter Bourgon's [Go: Best Practices for Production Environments](http://peter.bourgon.org/go-in-production/#formatting-and-style).
+* Commit your changes by making sure the commit messages convey the need and notes about the commit.
+* Push your changes to the branch in your fork of the repository.
+* Submit a pull request to the original repository. See [Pull Request checklist](#pull-request-checklist).
+
+## Pull Request Checklist
+
+* Rebase to the current master branch before submitting your pull request.
+* Commits should be as small as possible. Each commit should follow the checklist below:
+  - For code changes, add tests relevant to the fixed bug or new feature.
+  - Pass the compile and tests - includes spell checks, formatting, etc.
+  - Commit header (first line) should convey what changed.
+  - Commit body should include details such as why the changes are required and how the proposed changes.
+  - DCO Signed.
+* If your PR is not getting reviewed or you need a specific person to review it, please reach out to the OpenEBS Contributors. ( See [communicate](#communicate) )
+
+## Sign your work
+
+We use the Developer Certificate of Origin (DCO) as an additional safeguard for the OpenEBS project. This is a well established and widely used mechanism to assure that contributors have confirmed their right to license their contribution under the project's license. Please read [dcofile](https://github.com/openebs/openebs/blob/master/contribute/developer-certificate-of-origin). If you can certify it, then just add a line to every git commit message:
+
+```
+  Signed-off-by: Random J Developer <[email protected]>
+```
+
+Use your real name (sorry, no pseudonyms or anonymous contributions). The email id should match the email id provided in your GitHub profile.
+If you set your `user.name` and `user.email` in git config, you can sign your commit automatically with `git commit -s`.
+
+You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed.
+
+## Setting up your Development Environment
+
+This project is implemented using Go and uses the standard golang tools for development and build. In addition, this project heavily relies on Docker and Kubernetes. It is expected that the contributors:
+- are familiar with working with Go;
+- are familiar with Docker containers;
+- are familiar with Kubernetes and have access to a Kubernetes cluster or Minikube to test the changes.
+
+For setting up a Development environment on your local host, see the detailed instructions [here](./devel.md).
+
+## Communicate
+
+Reach out to OpenEBS [slack] to communicate with contributors.
+Also feel free to reach out to @sonasingh46 @mittachaitu @prateekpandey14 
+who are the owners for cstor-operators repository.
+
+
+[slack]: https://openebs-community.slack.com
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## Community Code of Conduct

		This project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).