technofab/zfs-localpv
1
0
Fork 0
mirror of https://github.com/TECHNOFAB11/zfs-localpv.git synced 2025-12-11 22:10:11 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore(doc): adding contributing doc

Browse source 
Signed-off-by: Pawan <pawan@mayadata.io>
This commit is contained in:
Pawan 2019-12-20 13:49:39 +05:30 • committed by Kiran Mova
parent 820d0800cd
commit 5c992a5ba4
2 changed files with 228 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

57
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,57 @@
# Contributing to zfs localpv
ZFS LocalPV 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 are maintained at [zfs-localpv/issues](https://github.com/openebs/zfs-localpv/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 [OpenEBS Community](https://github.com/openebs/openebs/tree/master/community)
## Steps to Contribute
ZFS-LocalPV 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 [zfs-localpv/issues](https://github.com/openebs/zfs-localpv/issues). You can pick up from a list of [good-first-issues](https://github.com/openebs/zfs-localpv/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 and clone.
* 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 and it should follow the commit [guideline](https://github.com/openebs/openebs/blob/master/contribute/git-commit-message.md)
- Commit body should include details such as why the changes are required and how the proposed changes help
- 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 [OpenEBS Community](https://github.com/openebs/openebs/tree/master/community)
## Sign your work
We use the Developer Certificate of Origin (DCO) as an additional safeguard for the OpenEBS projects. 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 <random@developer.example.org>
````
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](./docs/developer-setup.md).
The ZFS LocalPV design document is available [here](https://github.com/openebs/openebs/blob/master/contribute/design/1.x/csi/20190805-csi-zfspv-volume-provisioning.md).

171
docs/developer-setup.md Normal file
View file

@ -0,0 +1,171 @@
# Development Workflow
## Prerequisites
* You have Go 1.12.5 installed on your local host/development machine.
* You have Docker installed on your local host/development machine. Docker is required for building zfs-driver container images and to push them into a Kubernetes cluster for testing.
* You have `kubectl` installed. For running integration tests, you can create a Minikube cluster on local host/development machine. Don't worry if you don't have access to the Kubernetes cluster, raising a PR with the zfs-localpv repository will run integration tests for your changes against a Minikube cluster.
## Initial Setup
### Fork in the cloud
1. Visit https://github.com/openebs/zfs-localpv
2. Click `Fork` button (top right) to establish a cloud-based fork.
### Clone fork to local host
Place openebs/zfs-localpv's 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= your github profile name
git clone https://github.com/$user/zfs-localpv.git
# Configure remote upstream
cd $GOPATH/src/github.com/openebs/zfs-localpv
git remote add upstream https://github.com/openebs/zfs-localpv.git
# Never push to upstream master
git remote set-url --push upstream no_push
# Confirm that your remotes make sense:
git remote -v
```
> **Note:** If your `GOPATH` has more than one (`:` separated) paths in it, then you should use *one of your go path* instead of `$GOPATH` in the commands mentioned here. This statement holds throughout this document.
Install the build dependencies.
* Run `make bootstrap` to install the required Go tools
## Git Development Workflow
### Always sync your local repository:
Open a terminal on your local host. Change directory to the zfs-localpv fork root.
```sh
$ cd $GOPATH/src/github.com/openebs/zfs-localpv
```
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/zfs-localpv by listing them.
```sh
$ git remote -v
origin https://github.com/$user/zfs-localpv.git (fetch)
origin https://github.com/$user/zfs-localpv.git (push)
upstream https://github.com/openebs/zfs-localpv.git (fetch)
upstream https://github.com/openebs/zfs-localpv.git (no_push)
```
If the upstream is missing, add it by using below command.
```sh
$ git remote add upstream https://github.com/openebs/zfs-localpv.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/zfs-localpv
* 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://$user@github.com':
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/zfs-localpv.git
8e107a9..5035fa1 master -> master
```
### Contributing to a feature or bugfix.
Always start with creating a new branch from master to work on a new feature or bugfix. 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 master
# Make sure the master is rebased with the latest changes as described in previous step.
$ git checkout -b 1234-fix-developer-docs
Switched to a new branch '1234-fix-developer-docs'
```
Happy Hacking!
### Building and Testing your changes
* run `make` in the top directory. It will:
* Build the binary.
* Build the docker image with the binary.
* Test your changes
* setup the ZFS POOL on the nodes, check Setup in [readme](../README.md).
* Integration tests are written in ginkgo and run against a minikube cluster. Minikube cluster should be running so as to execute the tests. To install minikube follow the doc [here](https://kubernetes.io/docs/tasks/tools/install-minikube/).
* `sudo -E env "PATH=$PATH" make ci` execute the integration tests
### Keep your branch in sync
[Rebasing](https://git-scm.com/docs/git-rebase) is very import 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](../CONTRIBUTING.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/zfs-localpv github](https://github.com/openebs/zfs-localpv) and follow the Open Pull Request link to raise your PR from your development branch.