Skip to content

Commit 7ef18a6

Browse files
grighettojohnsmartco
grighetto
and
johnsmartco
authored
ZDM-374 CONTRIBUTING.md (#37)
Adds a CONTRIBUTING.md with some development guidelines. Co-authored-by: John Smart <[email protected]>
1 parent 0f44d25 commit 7ef18a6

File tree

6 files changed

+280
-242
lines changed

6 files changed

+280
-242
lines changed

‎CONTRIBUTING.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Contribution Guidelines
2+
3+
Thanks for your interest in contributing to the ZDM Proxy!
4+
5+
Below you'll find some guidelines to help you get started.
6+
There are multiple ways you can contribute to the project, you can open Pull Requests
7+
to fix a bug or add a new feature, report issues or improve the documentation.
8+
9+
The proxy is written in Go, so if you're already familiar with the language, you'll notice
10+
the project uses most of the standard tools and conventions in the Go ecosystem for code formatting, building
11+
and testing. But if you're still new to it, don't worry, we'll give you an overview in the next
12+
few sections.
13+
14+
- [Code Contributions](#code-contributions)
15+
- [Running Unit Tests](#running-unit-tests)
16+
- [Running Integration Tests](#running-integration-tests)
17+
- [Simulacron](#simulacron)
18+
- [CCM](#ccm)
19+
- [Running on Localhost with Docker Compose](#running-on-localhost-with-docker-compose)
20+
- [Debugging](#debugging)
21+
- [CPU and Memory Profiling](#cpu-and-memory-profiling)
22+
- [Pull Request Checks](#pull-request-checks)
23+
- [Code Formatting](#code-formatting)
24+
25+
## Code Contributions
26+
27+
---
28+
**Note:** If you'll contribute code or examples via a Pull Request (PR) to this ZDM Proxy project, be sure to first read
29+
the Contribution License Agreement (CLA) at https://cla.datastax.com/. You'll be required to sign it with your GitHub
30+
account before we can consider accepting your PR changes.
31+
---
32+
33+
**Before you start working on a feature or major change, we ask you to discuss your idea with the members
34+
of the community by opening an issue in GitHub, this way we can discuss design considerations and
35+
feasibility before you invest your time on the effort.**
36+
37+
When you're ready to code, follow these steps:
38+
39+
1. If you haven't done so yet, go ahead now and fork the ZDM Proxy repository into your own Github account and clone it
40+
on your machine. That's how you'll be able to make contributions, you cannot push directly to the main repository, but
41+
you can open a Pull Request for your branch when you're ready.
42+
43+
44+
2. From your fork, create a new local branch where you'll make changes. Give it a short, descriptive, name.
45+
If there's an associated issue open, include its number as a prefix, *#issue-name*, for example: 10-fix-bug-xyz.
46+
47+
48+
3. Make the changes you want locally and validate them with the [test tools](#running-unit-tests) provided. Push the
49+
updated code to the remote branch in your fork.
50+
51+
52+
4. Finally, when you're happy with your edits, open a Pull Request through the GitHub UI.
53+
54+
55+
5. The automated tests in GitHub Actions will kick in and in a few minutes you should
56+
have some results. If any of the checks fail, take a look at the workflow [logs](#pull-request-checks) to understand
57+
what happened. You can push more commits to the PR until the problem is resolved, the checks will run again.
58+
59+
60+
6. Once all checks are passing, your PR is ready for review and the members of the ZDM Proxy community will
61+
start the process. You may be asked to make further adjustments, this is an iterative process, but
62+
in the end if everything looks good, you'll be able to merge the PR to the main branch.
63+
64+
65+
7. Congratulations! At this point your code is ready to be released in the official distribution in the
66+
next release cycle. Keep an eye on the Releases page for new versions: https://github.com/datastax/zdm-proxy/releases
67+
68+
### Running Unit Tests
69+
70+
The main source code of the project is located under the [proxy](https://github.com/datastax/zdm-proxy/tree/main/proxy)
71+
folder, but you'll notice some files have the following name pattern `*_test.go` next to the main file,
72+
these are the unit tests. These tests are meant to run very quickly with no external dependencies.
73+
74+
To run the unit tests, go the root of the project in a terminal window and execute the following command:
75+
76+
> $ go test -v ./proxy/...
77+
78+
You should see a PASS or FAIL message at the end of the execution.
79+
80+
Make sure you add tests to your PR if you're making a major contribution.
81+
82+
### Running Integration Tests
83+
84+
The integration tests have different execution modes that allow you to test the proxy with
85+
an in-memory CQL server, a mock service ([Simulacron](https://github.com/datastax/simulacron)), or an actual database
86+
(managed by [CCM](https://github.com/riptano/ccm)).
87+
By the default, it will run both the in-memory and Simulacron tests, but you can selectively
88+
enable the ones you want with the command-line flags we'll see next.
89+
90+
#### Simulacron
91+
92+
Simulacron is a native protocol server simulator for Apache Cassandra&reg; written in Java. It allows us to test the
93+
protocol message exchanges over a socket from the proxy to the backend without having to run a fully-fledged database.
94+
95+
It needs to be installed separately, and for that follow the installation instructions available
96+
[here](https://github.com/datastax/simulacron#prerequisites).
97+
98+
Now set the `SIMULACRON_PATH` environment variable to the path of the jar file you downloaded in the previous step.
99+
100+
Simulacron relies on loopback aliases to simulate multiple nodes. On Linux or Windows, you shouldn't have anything to do.
101+
On MacOS, run this script:
102+
103+
```bash
104+
#!/bin/bash
105+
for sub in {0..4}; do
106+
echo "Opening for 127.0.$sub"
107+
for i in {0..255}; do sudo ifconfig lo0 alias 127.0.$sub.$i up; done
108+
done
109+
```
110+
It may take a couple of minutes for it to complete and settle down. Also, note that this does not survive reboots.
111+
112+
Now you should be ready to run the Simulacron tests with:
113+
114+
> $ go test -v ./integration-tests
115+
116+
#### CCM
117+
118+
Cassandra Cluster Manager (CCM) is a tool written in Python that manages local Cassandra installations for testing purposes.
119+
These tests will be run automatically by Github when you open a PR, but you can optionally run them locally too,
120+
for that follow the installation instructions available in the CCM [repository](https://github.com/riptano/ccm#installation).
121+
122+
Once you have CCM installed, run the tests with:
123+
124+
> $ go test -v ./integration-tests -RUN_CCMTESTS=true
125+
126+
By the default, that will include the mock tests too (CQL Server and Simulacron), but you can disabled them and run CCM
127+
only with:
128+
129+
> $ go test -v ./integration-tests -RUN_CCMTESTS=true -RUN_MOCKTESTS=false
130+
131+
In order to specify a specific Cassandra or DSE version, use the `CASSANDRA_VERSION` or `DSE_VERSION` flags, for example:
132+
133+
> $ go test -v ./integration-tests -RUN_CCMTESTS=true -CASSANDRA_VERSION=3.11.8
134+
135+
### Running on Localhost with Docker Compose
136+
137+
Sometimes you may want to run the proxy on localhost to do some manual validation, but in order to do anything meaningful
138+
with it, you'll need to connect it to two database clusters (ORIGIN and TARGET). To simplify the process we provide a
139+
[docker-compose](https://docs.docker.com/compose/) definition that handles the setup for you.
140+
141+
The definition will start two Cassandra clusters, one ZDM proxy instance and automatically run a NoSQLBench workload to
142+
verify the setup.
143+
144+
Start the services with the following command (this assumes you have docker-compose [installed](https://docs.docker.com/compose/install/)):
145+
146+
> $ docker-compose -f docker-compose-tests.yml up
147+
148+
After it completes, it will still keep the containers running in case you want to do any further inspection.
149+
To stop the services, hit CTRL+C and delete the containers with:
150+
151+
> $ docker-compose -f docker-compose-tests.yml down
152+
153+
### Debugging
154+
155+
Similarly, there's a docker-compose setup for debugging the proxy while connected to running clusters. The provided
156+
setup uses [Delve](https://github.com/go-delve/delve) to enable remote debugging so you can connect to the proxy from
157+
your IDE.
158+
159+
First, start docker-compose with the debug definition:
160+
161+
> $ docker-compose -f docker-compose-debug.yml up
162+
163+
Wait until you this message `API server listening at: [::]:2345`, then you'll know the debugger is ready.
164+
165+
Now attach your IDE to the debugger at `localhost:2345`. If you're using IntelliJ, check
166+
[this](https://www.jetbrains.com/help/go/attach-to-running-go-processes-with-debugger.html#step-4-start-the-debugging-process-on-the-client-computer)
167+
guide to learn how.
168+
169+
At this point the proxy is ready to receive requests, so enter some breakpoints in the IDE and connect some CQL client
170+
to the proxy at `localhost:9042`.
171+
172+
### CPU and Memory Profiling
173+
174+
During development, you may want to enable CPU and Memory profiling on the proxy to investigate some performance degradation.
175+
To do that, you'll have to build the proxy with profiling enabled first:
176+
177+
> $ go build -tags profiling
178+
179+
And then when you start the proxy, specify where to save the profile data:
180+
181+
> $ ./proxy -cpu_profile cpu.prof -mem_profile heap.prof
182+
183+
Note that these files will be created at the moment the proxy is stopped. These files can then be opened using the
184+
Go tool [pprof](https://go.dev/blog/pprof).
185+
186+
### Pull Request Checks
187+
188+
All the tests we described above are also executed in an automated fashion by a GitHub Workflow when you
189+
open a Pull Request.
190+
191+
Below you see an example of a PR that had some successful tests but a couple that failed.
192+
193+
![ZDM-PR-checks](docs/assets/ZDM-PR-checks.png)
194+
195+
To investigate the failures, click the `Details` link next to the job you're interested in and that will take you to
196+
execution logs. You can download the full log file by going to `Gear icon > Download log archive`:
197+
198+
![ZDM-PR-logs](docs/assets/ZDM-PR-logs.png)
199+
200+
In case you just want to see an overview of the test results, click the `Summary` link on the top left-hand side of the
201+
page, which will show you only the relevant pieces of the log for the failed tests.
202+
203+
![ZDM-PR-summary](docs/assets/ZDM-PR-summary.png)
204+
![ZDM-PR-summary-details](docs/assets/ZDM-PR-summary-details.png)

0 commit comments

Comments
 (0)