Skip to content

Commit 74cccfc

Browse files
kalebskeithleykalebskeithley
authored
Merge pull request #124 from Manimaran-MM/readme-dev-onboard
[README] Adding readme documentation
2 parents 22d513a + c1c3112 commit 74cccfc

File tree

3 files changed

+290
-0
lines changed

3 files changed

+290
-0
lines changed

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,7 @@ script to install and configure a server.
2424
The `pynfs` directory contains the `client.sh` script and a Jenkins `.xml` to
2525
run the tests from the pynfs project. The Jenkins `.xml` job runs the a common
2626
script to install and configure a server.
27+
28+
## Onboarding documentation
29+
- [Gatecheck CI tests onboarding](docs/ci_gatecheck.md)
30+
- [Sanity dev job onboarding](docs/dev_onborading.md)

‎docs/ci_gatecheck.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
## CI Tests – Onboarding (Gatecheck, Checkpatch/FSAL, PyNFS/Cthon)
2+
3+
### 1. What this pipeline does
4+
5+
- **Goal**: Validate an NFS-Ganesha patch with:
6+
- **Checkpatch** (style/lint)
7+
- **Clang-format** (formatting)
8+
- **FSAL build tests** (CephFS, VFS, RGW, GPFS)
9+
- **Cthon & PyNFS** protocol tests (separate job / test file)
10+
- **Key pieces**:
11+
- `jobs/Jenkinsfile.gatecheck` – Jenkins pipeline for gatecheck.
12+
- `tests/test_checkpatch_fsal.py` – Checkpatch, Clang, FSAL build tests.
13+
- `tests/test_pynfs_cthon.py` – Cthon & PyNFS tests across backends.
14+
- `ci_utils/*` – shared helpers for node handling, logging, remote sessions, NFS-Ganesha/FS backends, etc.
15+
- **Gatecheck pipeline**: [`Jenkinsfile.gatecheck` Jenkins job](https://jenkins-nfs-ganesha.apps.ocp.cloud.ci.centos.org/job/gatecheck-trigger-gerrithub/)
16+
17+
---
18+
19+
## 2. Jenkins gatecheck pipeline (`jobs/Jenkinsfile.gatecheck`)
20+
21+
- **Pre-flight**:
22+
- Uses `preCheckGerritPatchset()` to:
23+
- Query Gerrit for the latest patchset and mergeability.
24+
- Abort the build (with a Gerrit message) if:
25+
- A newer patchset exists, or
26+
- The change is not mergeable.
27+
- **Install dependencies**:
28+
- Installs Python + CI dependencies from `ci_utils/requirements.txt`.
29+
- **Run tests**:
30+
- Reserves nodes:
31+
- `pytest -v -s ci-tests/tests/test_reserve_nodes.py`
32+
- CI pre-reqs and environment:
33+
- `pytest -c ci-tests/ci_utils/pytest.ini -v -s -m checkpatch_fsal ci-tests/tests/test_ci_pre_req.py`
34+
- Checkpatch / Clang / FSAL build:
35+
- `pytest -v -n 6 --capture=no --junitxml=report-checkpatch-fsal.xml ci-tests/tests/test_checkpatch_fsal.py`
36+
- **Teardown & Gerrit reporting**:
37+
- Always:
38+
- `pytest -v -s ci-tests/tests/test_delete_nodes.py`
39+
- Cat failure/summary files under `${WORKSPACE}/failures` and summaries.
40+
- Uses `postToGerrit(...)` to:
41+
- Post a summary message and, if checkpatch/clang JSON is present, inline comments.
42+
- Adjust `Verified` label (e.g., `-1` if there are many comments).
43+
44+
**As a dev**: You typically don’t change this pipeline flow often; you extend tests and `ci_utils` and only tweak the pipeline for new stages or flags.
45+
46+
---
47+
48+
## 3. Checkpatch, Clang, FSAL tests (`tests/test_checkpatch_fsal.py`)
49+
50+
### 3.1. Common fixtures
51+
52+
- **Workspace & files**:
53+
- Uses `WORKSPACE` (defaults `/tmp`) and:
54+
- `duffy_session.json` – reserved nodes info.
55+
- `failures/` – JSON/log files.
56+
- `summary_checkpatch_fsal.txt`, `summary_status.txt` – human-readable + status summary.
57+
- **`server_node` (session fixture)**:
58+
- Reads first node IP from `duffy_session.json`.
59+
- **`create_session` (test fixture)**:
60+
- Connects via `RemoteSession` to `server_node`.
61+
- Creates a per-test directory `/root/<test_name>`.
62+
- Copies `${WORKSPACE}/nfs-ganesha` to the remote test dir.
63+
- **`cmake_config` / `cmake_flags`**:
64+
- Loads `ci_utils/config/cmake_flags.yml`.
65+
- Merges:
66+
- `default` + per-test flags + `CMAKE_FLAGS` env.
67+
- `CMAKE_OVERRIDE` env can bypass YAML and use only env flags.
68+
- **`attach_test_name`**:
69+
- Sets the current test name in logger for consistent logs.
70+
71+
### 3.2. Tests
72+
73+
- **`test_checkpatch`**:
74+
- Copies `build_scripts/checkpatch/checkpatch-to-gerrit-json.py` to remote.
75+
- Runs:
76+
- `git show --format=email HEAD~0` through `checkpatch.pl`.
77+
- Pipes into `checkpatch-to-gerrit-json.py` to produce JSON.
78+
- Handles:
79+
- `Checkpatch OK` → success.
80+
- Otherwise:
81+
- Parses JSON comments, drops exclusions (e.g. `/COMMIT_MSG`).
82+
- Writes `checkpatch_logs.json` when failing.
83+
- Flattens messages for Gerrit and writes summary (via `gerrit_custom_message`).
84+
85+
- **`test_clang_format`**:
86+
- Copies `build_scripts/clang/clangformat_to_gerrit_json.py`.
87+
- Runs:
88+
- `git clang-format` diff with `.clang-format`, pipes into converter script.
89+
- On failure:
90+
- Writes JSON and text logs under `failures/`.
91+
- Logs a Gerrit-friendly summary (again via `gerrit_custom_message`).
92+
93+
- **FSAL build tests** (e.g. CephFS):
94+
- Use `create_session` + `cmake_flags` to:
95+
- Configure and build NFS-Ganesha (e.g. CephFS FSAL).
96+
- Log summary and status to `summary_checkpatch_fsal.txt` / `summary_status.txt`.
97+
98+
**As a dev**:
99+
- To **add new lint/build checks**:
100+
- Add a new test function using `create_session`, and:
101+
- Run required tools on the remote workspace.
102+
- Write failures to a JSON/log under `${WORKSPACE}/failures`.
103+
- Call `gerrit_custom_message(code, "<Your check name>", out)`.
104+
105+
---
106+
107+
## 4. Cthon & PyNFS tests (`tests/test_pynfs_cthon.py`)
108+
109+
### 4.1. Common fixtures
110+
111+
- **Nodes and workspace**:
112+
- `SESSION_FILE` (`duffy_session.json`) and `BAREMETAL_SESSION_FILE` for reserved/baremetal nodes.
113+
- `FAILURE_FILE`, `SUMMARY_FILE`, `SUMMARY_STATUS` under `${WORKSPACE}`.
114+
- **`all_nodes` / `all_baremetal_nodes`**:
115+
- Read node lists from the session files.
116+
- **`create_session`**:
117+
- Parameterized fixture:
118+
- Accepts indices (e.g. `1` or `[0, 2]`).
119+
- Supports `@pytest.mark.baremetal` to pick from baremetal list.
120+
- For each requested node:
121+
- Opens `RemoteSession` with a per-test directory (`/root/<test_name>_<idx>`).
122+
- Copies `${WORKSPACE}/nfs-ganesha` to that dir.
123+
- Yields:
124+
- Single tuple `(session, default_dir, node_ip)` or list of tuples.
125+
- **`cmake_config` / `cmake_flags`**:
126+
- Same YAML + env merging pattern as in `test_checkpatch_fsal.py`.
127+
128+
### 4.2. Tests (examples)
129+
130+
- **`test_cthon_cephfs`**:
131+
- Node allocation: 1 server.
132+
- Steps:
133+
- Build & install NFS-Ganesha with CephFS flags.
134+
- Run `CephGaneshaSetup` → CephFS volume.
135+
- Run `GaneshaManager` → exports.
136+
- Use `CthonManager` to clone/build Cthon and run tests (skip NFSv3).
137+
- On failure:
138+
- Save Cthon logs to `failures/cthon_logs.txt`.
139+
- Write summary entry (pass/fail) to `SUMMARY_FILE` / `SUMMARY_STATUS`.
140+
141+
- **`test_pynfs_cephfs`**:
142+
- Node allocation: `[0, 2]` (client, server).
143+
- Steps:
144+
- Build & install NFS-Ganesha on server node.
145+
- Use `CephGaneshaSetup` + `GaneshaManager(test_type="pynfs")`.
146+
- On client node:
147+
- Use `PyNFSManager` to run tests against export `/nfs/cephfs` or similar.
148+
- Log failures and summary exactly as above.
149+
150+
- **Other tests in this file** follow a similar pattern for:
151+
- Different backends (**VFS, GPFS**, etc.).
152+
- Virtual machine flows via `VMManager`.
153+
- Additional Cthon/PyNFS combinations.
154+
155+
**As a dev**:
156+
- To **add a new protocol/backend test**:
157+
- Add a new test function reusing:
158+
- `@pytest.mark.parametrize("create_session", [...], indirect=True)`
159+
- `@pytest.mark.parametrize("cmake_flags", ["<flag-set>"], indirect=True)`
160+
- Use the appropriate `ci_utils` manager:
161+
- `CephGaneshaSetup`, `GPFSGaneshaManager`, `VFSGaneshaManager`, `VFSVolumeExporter`, `PyNFSManager`, `CthonManager`, `VMManager`.
162+
- Follow existing pattern for:
163+
- Build/install.
164+
- Backend setup and export.
165+
- Running Cthon/PyNFS/other workloads.
166+
- Logging to `FAILURE_FILE` and summary files.
167+
168+
---
169+
170+
## 5. Where to put shared code and how to extend
171+
172+
- **Shared logic**:
173+
- Always prefer adding helpers in `ci_utils`:
174+
- Node handling: `ci_utils/common`, `ci_utils/dev_space`, GPFS/Ceph/VFS setup modules, NFS-Ganesha managers.
175+
- Utilities: `remote_session.py`, `helpers.py`, `logger.py`, backend setup modules.
176+
- **Extending tests**:
177+
- For **new lint/static checks** → extend `tests/test_checkpatch_fsal.py`.
178+
- For **new backend or protocol flows** → extend `tests/test_pynfs_cthon.py`.
179+
- Respect:
180+
- Existing fixtures (no custom SSH logic if not needed).
181+
- Summary/JSON log pattern so `Jenkinsfile.gatecheck` and Gerrit integration keep working.

‎docs/dev_onborading.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
## Sanity Dev CI – Quick Onboarding Guide
2+
3+
### Overview
4+
5+
- **Goal**: Run and develop CI tests for **NFS-Ganesha** using the `sanity_dev` Jenkins job.
6+
- **Key pieces**:
7+
- `jobs/distributed_test_runner/sanity_dev.groovy` – defines the Jenkins job & parameters.
8+
- `jobs/Jenkinsfile.sanity_dev` – actual pipeline (checkout, install, run tests).
9+
- `tests/dev_space/` – dev-focused pytest suites (e.g. `test_fsal.py`).
10+
- `ci_utils/` – shared Python helpers.
11+
- `ci_utils/dev_space/` – dev-only helpers (dependencies, node reservation, etc.).
12+
- **Sanity dev pipeline**: [`sanity_dev` Jenkins job](https://jenkins-nfs-ganesha.apps.ocp.cloud.ci.centos.org/view/all/job/sanity_dev/)
13+
14+
---
15+
16+
## How the Jenkins Job Works
17+
18+
- **Job definition (`sanity_dev.groovy`)**
19+
- **Defines parameters**:
20+
- **`TEST_SUITE`**: which test file to run (e.g. `test_fsal` → `test_fsal.py`).
21+
- **`SERVER_NODE_COUNT`**, **`CLIENT_NODE_COUNT`**: how many nodes to reserve.
22+
- **`CI_REPO`/`CI_BRANCH`**: repo/branch for this CI framework (default is this repo).
23+
- **`GIT_REPO`/`GIT_BRANCH`**: NFS-Ganesha source to test.
24+
- **`CMAKE_FLAGS`**, **`CMAKE_OVERRIDE`**: extra/override CMake options.
25+
- **`CENTOS_VERSION`**, **`CENTOS_ARCH`**: OS/arch to use.
26+
- **Points to pipeline**: uses `jobs/Jenkinsfile.sanity_dev` from this repo.
27+
28+
- **Pipeline (`Jenkinsfile.sanity_dev`)**
29+
- **Checks out**:
30+
- CI repo → `ci-tests/`
31+
- NFS-Ganesha → `nfs-ganesha/` (with submodules).
32+
- **Installs deps** from `ci_utils/requirements.txt`.
33+
- **Runs pytest**:
34+
- `pytest -v -s ci-tests/tests/dev_space/${TEST_SUITE}.py`
35+
- Uses `PYTHONPATH=ci-tests` so `ci_utils.*` imports work.
36+
37+
---
38+
39+
## Where to Put Code
40+
41+
- **Common/shared helpers**: `ci_utils/`
42+
- Logging, remote sessions, Ceph/Ganesha setup, Cthon/PyNFS managers, etc.
43+
- **Dev-only helpers**: `ci_utils/dev_space/`
44+
- `dependencies.py`: install build/runtime deps on nodes.
45+
- `node_reservation.py`: reserve/release nodes.
46+
- **Dev test suites**: `tests/dev_space/`
47+
- Example: `test_fsal.py` – builds Ganesha, brings up CephFS, runs Cthon + PyNFS.
48+
49+
---
50+
51+
## Test Flow in `tests/dev_space/test_fsal.py` (Pattern to Follow)
52+
53+
- **Inputs from Jenkins**:
54+
- Reads env vars: `TEST_SUITE`, `SERVER_NODE_COUNT`, `CLIENT_NODE_COUNT`, `CMAKE_FLAGS`, `CMAKE_OVERRIDE`, `CENTOS_VERSION`, `CENTOS_ARCH`.
55+
- **Session-level fixtures (auto-used)**:
56+
- **`ci_params`**: parses env vars into a dict.
57+
- **`reserved_nodes`**: calls `reserve_nodes()` / `delete_nodes()` once per run.
58+
- **`remote_sessions`**: opens SSH (`RemoteSession`) to servers/clients.
59+
- **`cmake_config` + `cmake_flags`**:
60+
- Loads flags from `ci_utils/config/cmake_flags.yml`.
61+
- Merges with `CMAKE_FLAGS`, respects `CMAKE_OVERRIDE`.
62+
- **Tests**:
63+
- **`test_cephfs_fsal`**: copy Ganesha to server, build with CMake flags, assert build success.
64+
- **`test_bringup_cephfs`**: `make install`, setup CephFS + Ganesha, assert setup.
65+
- **`test_cthon`**: run Cthon tests from client.
66+
- **`test_pynfs`**: run PyNFS tests from client.
67+
68+
Use this pattern (fixtures + managers from `ci_utils`) for any new dev tests.
69+
70+
---
71+
72+
## Typical Dev Workflow
73+
74+
- **To run via Jenkins**:
75+
- Open **`sanity_dev`** job.
76+
- Set:
77+
- **`TEST_SUITE`**: e.g. `test_fsal`.
78+
- **Node counts**: `SERVER_NODE_COUNT`, `CLIENT_NODE_COUNT`.
79+
- **Repos/branches**: change `GIT_REPO`/`GIT_BRANCH` if testing your fork.
80+
- Optional: `CMAKE_FLAGS` / `CMAKE_OVERRIDE`, `CENTOS_VERSION`.
81+
- Start build, inspect:
82+
- “Checkout CI Tests” → “Checkout NFS-Ganesha” → “Install Dependencies” → “Run tests”.
83+
84+
---
85+
86+
## How to Add a New Dev Test Suite
87+
88+
- **1. Add a test file** under `tests/dev_space/`
89+
- Example: `tests/dev_space/test_newbackend.py`.
90+
- Reuse fixtures from `test_fsal.py`:
91+
- `ci_params`, `reserved_nodes`, `remote_sessions`, `cmake_flags`.
92+
- Use `ci_utils` helpers to:
93+
- Reserve nodes, connect via SSH, setup backends, run tests.
94+
95+
- **2. Wire it up in Jenkins**
96+
- In `jobs/distributed_test_runner/sanity_dev.groovy`:
97+
- Add your test suite name to `TEST_SUITE` choices (e.g. `'test_newbackend'`).
98+
- In `jobs/Jenkinsfile.sanity_dev`:
99+
- Make sure `pytest` call matches the pattern:
100+
- `ci-tests/tests/dev_space/${params.TEST_SUITE}.py`.
101+
- Optionally expand the `suiteFileMap` for logging.
102+
103+
- **3. Optional: add CMake flags**
104+
- Edit `ci_utils/config/cmake_flags.yml`:
105+
- Add `tests: test_newbackend: [...]` for per-test flags.

0 commit comments

Comments
 (0)