Skip to content

Latest commit

 

History

History
312 lines (226 loc) · 9.94 KB

developer-setup.md

File metadata and controls

312 lines (226 loc) · 9.94 KB

Development Workflow

Prerequisites

System Packages

  • You need to have a docker service installed on your local host/development machine. Docker is required for building lvm-driver container images and to push them into a Kubernetes cluster for testing.

Nix

This is the recommend way of setting up a development environment. Usually Nix can be installed via (Do not use sudo!):

curl -L https://nixos.org/nix/install | sh

Can't install Nix, or don't want to?

That's totally fine, you'll need the following additional system packages:

  • Go 1.19
  • kubectl

Fork in the cloud

  1. Visit https://github.com/openebs/lvm-localpv
  2. Click Fork button (top right) to establish a cloud-based fork.

Clone fork to local host

Place openebs/lvm-localpv's code on your local machine using the following cloning procedure:

$ mkdir -p ~/git
$ cd ~/git
# $user is your github user
$ git clone https://github.com/$user/lvm-localpv.git # you may use ssh instead
$ cd lvm-localpv
$ git remote add upstream https://github.com/openebs/lvm-localpv.git
# Don't push to upstream directly
$ git remote set-url --push upstream no_push

Git Development Workflow

Always sync your local repository

Checkout the develop branch.

$ cd ~/git/lvm-localpv
$ git checkout develop
Switched to branch 'develop'
Your branch is up-to-date with 'origin/develop'.

Recall that origin/develop is a branch on your remote GitHub repository. Make sure you have the upstream remote openebs/lvm-localpv by listing them.

$ git remote -v
origin https://github.com/$user/lvm-localpv.git (fetch)
origin https://github.com/$user/lvm-localpv.git (push)
upstream https://github.com/openebs/lvm-localpv.git (fetch)
upstream https://github.com/openebs/lvm-localpv.git (no_push)

If the upstream is missing, add it by using below command.

git remote add upstream https://github.com/openebs/lvm-localpv.git

Fetch all the changes from the upstream develop branch.

$ git fetch upstream develop
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/lvm-localpv
  * branch            develop     -> FETCH_HEAD

Rebase your local develop with the upstream/develop.

$ git rebase upstream/develop
First, rewinding head to replay your work on top of it...
Fast-forwarded develop to upstream/develop.

This command applies all the commits from the upstream develop to your local develop.

Check the status of your local branch.

$ git status
On branch develop
Your branch is ahead of 'origin/develop' 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 develop.

Push the rebased develop to origin develop.

$ git push origin develop
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/lvm-localpv.git
8e107a9..5035fa1  develop -> develop

Contributing to a feature or bugfix

Always start with creating a new branch from develop 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:

$ git checkout develop
# Make sure the develop 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!

Keep your branch in sync

Rebasing 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.

# While on your myfeature branch (see above)
$ git fetch upstream
$ git rebase upstream/develop

While you rebase your changes, you must resolve any conflicts that might arise and build and test your changes using the above steps.

Building

Before starting, ensure you have installed all the dependencies. If you're using nix, then simply enter the nix-shell which will setup a shell with all required packages:

$ nix-shell
go: downloading ....
....

NOTE: you can keep using your favorite shell by running it, example: nix-shell --run zsh.

On non-nix environments, run make bootstrap to install the required Go tools.

We have several make commands available at your convenience:

  • make bootstrap: as seen previously, installs all the required Go tools.
  • make format: will ensure the code is formatted according to the the guidelines.
  • make golint: comprehensive linter that helps catch potential issues such as coding style problems, possible bugs, and performance issues.
  • make clean: cleans all the installed Go tools, intermediate and generated artifacts.
  • make: builds the binary and a test docker image.

There are more commands, take your time to read through the the Makefile and Makefile-buildx.

Testing

Simple unit testing can be done via make:

$ make test
--> Running go fmt
--> Running go test
ok      github.com/openebs/lvm-localpv/pkg/driver       0.010s  coverage: 1.5% of statements
?       github.com/openebs/lvm-localpv/pkg/driver/config        [no test files]
?       github.com/openebs/lvm-localpv/pkg/equality     [no test files]
ok      github.com/openebs/lvm-localpv/pkg/lvm  0.008s  coverage: 14.7% of statements
?       github.com/openebs/lvm-localpv/pkg/mgmt/lvmnode [no test files]
...

The ci tests perform a more comprehensive testing, we need to make use of a Kubernetes cluster.
Sadly at this point in time, the ci tests expect to be running on a throw-away single node K8s cluster.
This means your development/testing system must be running on this very same node. \

Kubernetes Clusters

We suggest a few options for this:

NixOs-Shell

If you're already using nix-shell, then why not take this option?
How does it work?
It spawns a headless qemu virtual machines based on a configuration file and it provides console access in the same terminal window.

The provided configuration file deploys as a single node K3s cluster with the required LVM2 tools.

If you're already on the nix-shell, simply run it:

$ nixos-shell
Welcome to NixOS 24.11 (Vicuna)!

[  OK  ] Created slice Slice /system/getty.
[  OK  ] Created slice Slice /system/modprobe.
[  OK  ] Created slice Slice /system/serial-getty
....
[  OK  ] Reached target Network is Online.
         Starting Docker Application Container Engine...
         Starting k3s service...
[  OK  ] Started Docker Application Container Engine.

<<< Welcome to NixOS 24.11.712512.3f0a8ac25fb6 (x86_64) - hvc0 >>>
Log in as "root" with an empty password.
Run 'nixos-help' for the NixOS manual.
nixos login: root

Simply log in with the root user (no password) get hacking! To leave this shell you can use the key combination Ctrl-a x. You can then enter the nixos-shell again using the same command. If you've made irreparable damage to the virtual machine, simply delete it and start anew. This is as simple as:

# Leave the vm terminal and run:
rm nixos.qcow2
nixos-shell

MiniKube

To install minikube follow the doc here.
Setup the LVM Volume Group on the host, check Setup in readme.

NOTE: the minikube cluster must be started with the none driver

Running the tests

Integration tests are written in ginkgo and run against a K8s cluster.

NOTE: For nixos-shell, remember to run these command within the nixos-shell vm!

Then you can run the tests:

./ci/ci-test.sh run

WARNING: Each individual tests don't currently clean up after themselves properly, so a failed test may affect subsequent tests and even new test runs!

If the test script was killed before cleaning up, you can issue a cleanup as such:

./ci/ci-test.sh clean

You can also request one before running the tests:

./ci/ci-test.sh run --reset

WARNING: If you modify the code, remember to rebuild and load the new image, example:

./ci/ci-test.sh run --build-always

If this doesn't work, you might need to dig a little deeper, or, if you're on nixos-shell, simply start over again:

rm nixos.qcow2
nixos-shell

And there you have it, a clean VM ready to be broken again :)

Submission

Create a pull request

Before you raise the Pull Requests, ensure you have reviewed the checklist in the CONTRIBUTING GUIDE:

  • 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/lvm-localpv github and follow the Open Pull Request link to raise your PR from your development branch.