Merge pull request #304 from humblec/contributing

Add coding.md into docs

README.md

@@ -5,8 +5,8 @@ Card](https://goreportcard.com/badge/github.com/ceph/ceph-csi)](https://goreport
 [![Build
 Status](https://travis-ci.org/ceph/ceph-csi.svg?branch=master)](https://travis-ci.org/ceph/ceph-csi)
 
-[Container Storage Interface
-(CSI)](https://github.com/container-storage-interface/) driver, provisioner,
+This repo containes [Container Storage Interface(CSI)]
+(<https://github.com/container-storage-interface/>) driver, provisioner,
 and attacher for Ceph RBD and CephFS.
 
 ## Overview
@@ -75,6 +75,13 @@ deployments](https://github.com/ceph/ceph-csi/tree/csi-v1.0/deploy/).
 Please refer to the [matrix](https://kubernetes-csi.github.io/docs/#kubernetes-releases)
 in the Kubernetes documentation.
 
+## Contributing to this repo
+
+Please follow [development-guide]
+(<https://github.com/ceph/ceph-csi/tree/master/docs/development-guide.md>) and
+[coding style guidelines](<https://github.com/ceph/ceph-csi/tree/master/docs/coding.md>)
+if you are interested to contribute to this repo.
+
 ## Troubleshooting
 
 Please submit an issue at: [Issues](https://github.com/ceph/ceph-csi/issues)

docs/coding.md

@@ -0,0 +1,75 @@
+# Coding Conventions
+
+Please follow coding conventions and guidelines described in the following documents:
+
+* [Go proverbs](https://go-proverbs.github.io/) - highly recommended read
+* [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments)
+* [Effective Go](https://golang.org/doc/effective_go.html)
+* [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
+
+Here's a list of some more specific conventions that are often followed in
+the code and will be pointed out in the review process:
+
+## General
+
+* Keep variable names short for variables that are local to the function.
+* Do not export a function or variable name outside the package until you
+  have an external consumer for it.
+* Do not use named return values in function definitions. Use only the type.
+  Exception: defer()'d functions.
+
+### Imports
+
+We use the following convention for specifying imports:
+
+```
+<import standard library packages>
+
+<import third-party packages>
+
+<import ceph-csi packages>
+```
+
+Example:
+
+```go
+import (
+ "os"
+ "path"
+ "strings"
+ "time"
+
+ "github.com/pborman/uuid"
+ "github.com/pkg/errors"
+
+ "github.com/ceph/ceph-csi/pkg/util"
+)
+```
+
+### Error Handling
+
+* Use variable name `err` to denote error variable during a function call.
+* Reuse the previously declared `err` variable as long as it is in scope.
+  For example, do not use `errWrite` or `errRead`.
+* Do not panic() for errors that can be bubbled up back to user. Use panic()
+  only for fatal errors which shouldn't occur.
+* Do not ignore errors using `_` variable unless you know what you're doing.
+* Error strings should not start with a capital letter.
+* If error requires passing of extra information, you can define a new type
+* Error types should end with `Error`.
+
+### Logging
+
+* If a function is only invoked as part of a transaction step, always use the
+  transaction's logger to ensure propagation of request ID and transaction ID.
+* The inner-most utility functions should never log. Logging must almost always
+  be done by the caller on receiving an `error`.
+* Always use log level `DEBUG` to provide useful **diagnostic information** to
+  developers or sysadmins.
+* Use log level `INFO` to provide information to users or sysadmins. This is the
+  kind of information you'd like to log in an out-of-the-box configuration in
+  happy scenario.
+* Use log level `WARN` when something fails but there's a workaround or fallback
+  or retry for it and/or is fully recoverable.
+* Use log level `ERROR` when something occurs which is fatal to the operation,
+  but not to the service or application.

docs/development-guide.md

@@ -0,0 +1,91 @@
+# Development Guide
+
+## New to Go
+
+Ceph-csi is written in Go and if you are new to the language,
+it is **highly** encouraged to:
+
+* Take the [A Tour of Go](http://tour.golang.org/welcome/1) course.
+* [Set up](https://golang.org/doc/code.html) Go development environment on your machine.
+* Read [Effective Go](https://golang.org/doc/effective_go.html) for best practices.
+
+## Development Workflow
+
+### Workspace and repository setup
+
+* [Download](https://golang.org/dl/) Go (>=1.11.x) and
+   [install](https://golang.org/doc/install) it on your system.
+* Setup the [GOPATH](http://www.g33knotes.org/2014/07/60-second-count-down-to-go.html)
+   environment.
+* Run `$ go get -d github.com/ceph/ceph-csi`
+   This will just download the source and not build it. The downloaded source
+   will be at `$GOPATH/src/github.com/ceph/ceph-csi`
+* Fork the [ceph-csi repo](https://github.com/ceph/ceph-csi) on Github.
+* Add your fork as a git remote:
+   `$ git remote add fork https://github.com/<your-github-username>/ceph-csi`
+
+> Editors: Our favorite editor is vim with the [vim-go](https://github.com/fatih/vim-go)
+> plugin, but there are many others like [vscode](https://github.com/Microsoft/vscode-go)
+
+### Building Ceph-CSI
+
+To build ceph-csi run:
+`$ make`
+
+The built binary will be present under `_output/` directory.
+
+### Code contribution workflow
+
+ceph-csi repository currently follows GitHub's
+[Fork & Pull] (<https://help.github.com/articles/about-pull-requests/>) workflow
+for code contributions.
+
+Please read the [coding guidelines](coding.md) document before submitting a PR.
+
+Here is a short guide on how to work on a new patch.  In this example, we will
+work on a patch called *hellopatch*:
+
+* `$ git checkout master`
+* `$ git pull`
+* `$ git checkout -b hellopatch`
+
+Do your work here and commit.
+
+Run the test suite, which includes linting checks, static code check, and unit
+tests:
+
+`$ make test`
+
+You will need to provide unit tests and functional tests for your changes
+wherever applicable.
+
+Once you are ready to push, you will type the following:
+
+`$ git push fork hellopatch`
+
+**Creating A Pull Request:**
+When you are satisfied with your changes, you will then need to go to your repo
+in GitHub.com and create a pull request for your branch. Automated tests will
+be run against the pull request. Your pull request will be reviewed and merged.
+
+If you are planning on making a large set of changes or a major architectural
+change it is often desirable to first build a consensus in an issue discussion
+and/or create an initial design doc PR. Once the design has been agreed upon
+one or more PRs implementing the plan can be made.
+
+**Review Process:**
+Once your PR has been submitted for review the following critieria will
+need to be met before it will be merged:
+
+* Each PR needs reviews accepting the change from at least two developers
+* for merging
+  * It is common to request reviews from those reviewers automatically suggested
+  * by github
+* Each PR needs to have been open for at least 24 working hours to allow for
+* community feedback
+  * The 24 working hours counts hours occuring Mon-Fri in the local timezone
+  * of the submitter
+* Each PR must be fully updated to master and tests must have passed
+
+When the criteria are met, a project maintainer can merge your changes into
+the project's master branch.