From f0ea32010411f033f506806955ea1af59aadc0db Mon Sep 17 00:00:00 2001 From: Humble Chirammal Date: Thu, 4 Apr 2019 12:13:48 +0530 Subject: [PATCH] Update readme to point to development and contributing guide. Signed-off-by: Humble Chirammal --- README.md | 11 +++++- docs/coding.md | 24 ++++++------ docs/development-guide.md | 79 ++++++++++++++++++++++++--------------- 3 files changed, 68 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 007b22e9f..940268f51 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Ceph CSI 1.0.0 -[Container Storage Interface -(CSI)](https://github.com/container-storage-interface/) driver, provisioner, +This repo containes [Container Storage Interface(CSI)] +() driver, provisioner, and attacher for Ceph RBD and CephFS. ## Overview @@ -20,6 +20,13 @@ CephFS CSI plugins, see documentation in `docs/`. For example usage of RBD and CephFS CSI plugins, see examples in `examples/`. +## Contributing to this repo + +Please follow [development-guide] +() and +[coding style guidelines]() +if you are interested to contribute to this repo. + ## Troubleshooting Please submit an issue at: [Issues](https://github.com/ceph/ceph-csi/issues) diff --git a/docs/coding.md b/docs/coding.md index 2547724a3..f042dd9a8 100644 --- a/docs/coding.md +++ b/docs/coding.md @@ -10,12 +10,11 @@ Please follow coding conventions and guidelines described in the following docum 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 +## 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. -* Have setter or getter interfaces/methods to access/manipulate information in - a different package. * Do not use named return values in function definitions. Use only the type. Exception: defer()'d functions. @@ -26,25 +25,24 @@ We use the following convention for specifying imports: ``` - - + + ``` Example: ```go import ( - "os" - "path" - "strings" - "time" + "os" + "path" + "strings" + "time" - "github.com/ceph/ceph-csi/pkg/util" - - "github.com/pborman/uuid" - "github.com/pkg/errors" + "github.com/pborman/uuid" + "github.com/pkg/errors" + "github.com/ceph/ceph-csi/pkg/util" ) ``` diff --git a/docs/development-guide.md b/docs/development-guide.md index dbc8610b8..24bd14843 100644 --- a/docs/development-guide.md +++ b/docs/development-guide.md @@ -1,5 +1,9 @@ -## New to Go? -Glusterd2 is written in Go and if you are new to the language, it is **highly** encouraged to: +# 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. @@ -9,16 +13,19 @@ Glusterd2 is written in Go and if you are new to the language, it is **highly** ### Workspace and repository setup -1. [Download](https://golang.org/dl/) Go (>=1.9) and [install](https://golang.org/doc/install) it on your system. -1. Setup the [GOPATH](http://www.g33knotes.org/2014/07/60-second-count-down-to-go.html) environment. -1. 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` -1. Fork the [ceph-csi repo](https://github.com/ceph/ceph-csi) on Github. -1. Add your fork as a git remote: +* [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//ceph-csi` -1. Run `$ ./scripts/install-reqs.sh` -> 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). +> 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 @@ -27,48 +34,58 @@ To build ceph-csi run: The built binary will be present under `_output/` directory. -The built binary will be installed under `$GOPATH/bin/` 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. +ceph-csi repository currently follows GitHub's +[Fork & Pull] () 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*: +Here is a short guide on how to work on a new patch. In this example, we will +work on a patch called *hellopatch*: -1. `$ git checkout master` -2. `$ git pull` -3. `$ git checkout -b 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 tests` +`$ make test` You will need to provide unit tests and functional tests for your changes -wherever applicable. Ensure that the tests pass with your changes. The -functional tests needs to be run as root user. To run the functional tests: - -`# make functest` +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. +**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. +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 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 +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. +When the criteria are met, a project maintainer can merge your changes into +the project's master branch.