Skip to content

Commit

Permalink
docs: refactor contributing, testing and devel-quick-start
Browse files Browse the repository at this point in the history 
The flow of the documentation for a developer workflow wasn't clean. We
lay the main conditions of contributing in the contributing guide. The
developer workflow is now all in the devel-quick-start guide and testing
processes are contained in the testing doc.

Signed-off-by: Raghavendra Talur <[email protected]>
  • Loading branch information
@raghavendra-talur
raghavendra-talur committed Mar 5, 2024
1 parent db20325 commit a7ca85c
Show file tree
Hide file tree
Showing 3 changed files with 161 additions and 200 deletions.
63 changes: 7 additions & 56 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ SPDX-License-Identifier: Apache-2.0

# How to Contribute

The Ramen project in under [Apache 2.0 license](LICENSES/Apache-2.0.txt).
The Ramen project is under [Apache 2.0 license](LICENSES/Apache-2.0.txt).
We accept contributions via GitHub pull requests. This document outlines
some of the conventions related to development workflow to make it
easier to get your contribution accepted.
Expand All @@ -26,64 +26,15 @@ This is my commit message
Signed-off-by: Random J Developer <[email protected]>
```

Git even has a -s command line option to append this automatically to your
commit message:

```
git commit -s -m 'This is my commit message'
```

If you have already made a commit and forgot to include the sign-off, you can
amend your last commit to add the sign-off with the following command, which
can then be force pushed.

```
git commit --amend -s
```

## Getting Started

1. Fork the repository on GitHub
1. Read the [install](docs/install.md) guide for build and deploy instructions
1. Play with the project, submit bugs, submit patches!

## Contribution Flow

This is a rough outline of what a contributor's workflow looks like:

1. Create a branch from where you want to base your work (usually main).
1. Make your changes and arrange them in readable commits.
1. Make sure your commit messages are in the proper format (see below).
1. Push your changes to the branch in your fork of the repository.
1. Make sure all [tests](docs/testing.md) pass, and add any new [tests](docs/testing.md)
as appropriate.
1. Submit a pull request to the original repository.

## Coding Style

Ramen project is written in golang and follows the style guidelines dictated
by the go fmt as well as go vet tools.
Ramen project is written in golang and follows the style guidelines dictated by
the go fmt as well as go vet tools.

Additionally various golang linters are enforced to ensure consistent coding
style, these can be run using, `make lint` and in turn uses [golangci](https://golangci-lint.run/)
with [this](.golangci.yaml) configuration.

Several other linters are run on the pull request using the
[pre-commit.sh](hack/pre-commit.sh) script.
style.

### Pull Request Flow

The general flow for a pull request approval process is as follows:
## Getting Started

1. Author submits the pull request
1. Reviewers and maintainers for the applicable code areas review the pull
request and provide feedback that the author integrates
1. Reviewers and/or maintainers signify their LGTM on the pull request
1. A maintainer approves the pull request based on at least one LGTM from the
previous step
1. Note that the maintainer can heavily lean on the reviewer for examining
the pull request at a finely grained detailed level. The reviewers are
trusted members and maintainers can leverage their efforts to reduce
their own review burden.
1. A maintainer merges the pull request into the target branch (main, release,
etc.)
1. Read the [devel-quick-start](docs/devel-quick-start.md) guide for build, test
and contributing instructions.
204 changes: 62 additions & 142 deletions docs/devel-quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,36 +5,31 @@ SPDX-License-Identifier: Apache-2.0

# Ramen developer quick start guide

This page will help you to set up a development environment for the
*Ramen* project.
## Contribution Flow

## What you’ll need

To set up a *Ramen* development environment you will need to run 3
Kubernetes clusters. *Ramen* makes this easy using minikube, but you need
enough resources:

- Bare metal or virtual machine with nested virtualization enabled
- 8 CPUs or more
- 16 GiB of free memory
- 20 GiB of free disk space
- Internet connection
- Linux - tested on *RHEL* 8.6 and *Fedora* 37.
1. Fork the repository on GitHub
1. Create a branch from where you want to base your work (usually main).
1. Make your changes and arrange them in readable commits.
1. Make sure your commit messages are in the proper format.
1. Make sure all [tests](docs/testing.md) pass, and add any new [tests](docs/testing.md)
1. Push your changes to the branch in your fork of the repository.
as appropriate.
1. Submit a pull request to the original repository.

## Getting the source

1. Fork the *Ramen* repository on github

1. Clone the source locally

```
```sh
git clone [email protected]:my-github-user/ramen.git
```

1. Add an `upstream` remote, to make it easy to sync your repo from
upstream.

```
```sh
git remote add upstream https://github.com/RamenDR/ramen.git
```

Expand All @@ -44,7 +39,7 @@ enough resources:
footer in the commit message. To add it automatically to all commits,
add this hook:

```
```sh
$ cat .git/hooks/commit-msg
#!/bin/sh
# Add Signed-off-by trailer.
Expand All @@ -54,175 +49,100 @@ enough resources:

And make the hook executable:

```
```sh
chmod +x .git/hooks/commit-msg
```

1. Create python virtual environment

The *Ramen* project use python tool to create and provision test
environment and run tests. The create a virtual environment including
the tools run:
## Setting up the environment for development and testing

```
make venv
```

This create a virtual environment in `~/.venv/ramen` and a symbolic
link `venv` for activating the environment. To activate the
environment use:

That's all! You are ready to submit your first pull request!

## Running the tests

To run all unit tests run:

```
make test
```
To set up a *Ramen* development environment you will need to run 3
Kubernetes clusters. *Ramen* makes this easy using minikube, but you need
enough resources:

To run only part of the test suite you can use one of the `test-*`
targets, for example:
- Bare metal or virtual machine with nested virtualization enabled
- 8 CPUs or more
- 16 GiB of free memory
- 20 GiB of free disk space
- Internet connection
- Linux - tested on *RHEL* 8.6 and *Fedora* 37.

```
make test-vrg-vr
```
### Create and activate python virtual environment

To open an HTML coverage report in the default browser run:
The *Ramen* project uses python tools to create and provision test
environment and run tests. To create a virtual environment including
the tools run:

```sh
make venv
```
make coverage
```

The coverage report depends on the tests ran before inspecting the
coverage.

## Setting up the `drenv` tool

*Ramen* uses the `drenv` tool to build a development environment
quickly. Please follow the
[Setup instructions](../test/README.md#setup)
to set up the `drenv` tool.

## Starting the test environment
This creates a virtual environment in `~/.venv/ramen` and a symbolic
link `venv` for activating the environment.

Before using the `drenv` tool to start a test environment, you need to
activate the python virtual environment:
Activate the python virtual environment:

```
```sh
source venv
```

*Ramen* supports many configurations, but the only development
environment available now is the `regional-dr.yaml`. This environment
simulates a Regional DR setup, when the managed clusters are located in
different zones (e.g. US, Europe) and storage is replicated
asynchronously. This environment includes 3 clusters - a hub cluster
(`hub`), and 2 managed clusters (`dr1`, `dr2`) using `Ceph` storage.

To start the environment, run:

```
cd test
drenv start envs/regional-dr.yaml
```
### Create the environment

Starting takes at least 5 minutes, depending on your machine and
internet connection.
You can run the make target `create-rdr-env` to create a 3 cluster environment
for suitable for Regional DR. This will create 3 minikube clusters, and install
the necessary components for the Ramen operator to run.

You can inspect the environment using kubectl, for example:
This uses `drenv` tool to setup the environment. Refer to
[drenv readme](../test/README.md#setup) for more details.

```
kubectl get deploy -A --context hub
kubectl get deploy -A --context dr1
kubectl get deploy -A --context dr2
```sh
make create-rdr-env
```

## Building the ramen operator image

Build the *Ramen* operator container image:

```
```sh
make docker-build
```

This builds the image `quay.io/ramendr/ramen-operator:latest`

## Deploying the ramen operator

To deploy the *Ramen* operator in the test environment:

```
ramenctl deploy test/envs/regional-dr.yaml
```

## Configure the ramen operator on the hub

Ramen need to be configured to know about the managed clusters and the
s3 endpoints. To configure the ramen operator for test environment:

```
ramenctl config test/envs/regional-dr.yaml
```

For more info on the `ramenctl` tool see
You can either deploy the *Ramen* operator using the make targets or use the
`ramenctl` tool. For more info on the `ramenctl` tool see
[ramenctl/README.md](../ramenctl/README.md).

## Running system tests
- Using `ramenctl`

At this point *Ramen* is ready to protect workloads in your cluster, and
you are ready for testing basic flows.
Ensure python virtual environment is active as `ramenctl` is a python tool.
The default name-prefix in the make target `create-rdr-env` is `rdr-`, we
will use the same in the `ramenctl` commands.

To run basic tests using regional-dr environment run:
- Deploy the *Ramen* operator in the environment using `ramenctl`.

```
test/basic-test/run test/envs/regional-dr.yaml
```
```sh
ramenctl deploy --name-prefix rdr- test/envs/regional-dr.yaml
```

This test:
- Ramen needs to be configured to know about the managed clusters and the s3
endpoints. Configure the ramen operator for environment.

1. Deploys an application using
[ocm-ramen-samples repo](https://github.com/RamenDR/ocm-ramen-samples)
1. Enables DR for the application
1. Fails over the application to the other cluster
1. Relocates the application back to the original cluster
1. Disables DR for the application
1. Undeploys the application
```sh
ramenctl config --name-prefix rdr- test/envs/regional-dr.yaml
```

If needed, you can run one or more steps form this test, for example to
deploy and enable DR run:
## Testing Ramen

```
env=$PWD/test/envs/regional-dr.yaml
test/basic-test/deploy $env
test/basic-test/enable-dr $env
```

At this point you can run run manually failover, relocate one or more
times as needed:

```
for i in $(seq 3); do
test/basic-test/relocate $env
done
```

To clean up run:

```
test/basic-test/undeploy $env
```

For more info on writing such tests see
[test/README.md](../test/README.md).
- Read the [testing](./testing.md) guide for test instructions.

## Undeploying the ramen operator

If you want to clean up your environment, you can unconfigure *Ramen* and
undeploy it.

```
ramenctl unconfig test/envs/regional-dr.yaml
ramenctl undeploy test/envs/regional-dr.yaml
```sh
ramenctl unconfig --name-prefix rdr- test/envs/regional-dr.yaml
ramenctl undeploy --name-prefix rdr- test/envs/regional-dr.yaml
```
Loading

0 comments on commit a7ca85c

Please sign in to comment.