Skip to content

Commit 3734076

Browse files
smuppandsmuppand
committed
docs: add comprehensive contribution guide for test structure and ShellCheck compliance
- Moved CONTRIBUTING.md to doc-friendly format - Added sample run.sh pseudocode with .res file requirement - Clarified folder structure and naming conventions - Included ShellCheck enforcement and POSIX shell compatibility - Outlined expectations for CI/CD and result file parsing Signed-off-by: Srikanth Muppandam <[email protected]>
1 parent 266d96d commit 3734076

File tree

1 file changed

+231
-35
lines changed

1 file changed

+231
-35
lines changed

‎CONTRIBUTING.md‎

Lines changed: 231 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,257 @@
11
# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
22
# SPDX-License-Identifier: BSD-3-Clause-Clear
33

4-
# Contributing to the Shell Scripts Repository
4+
# 🛠️ Contributing to qcom-linux-testkit
55

6-
Welcome! This repository contains hardware validation shell scripts for Qualcomm embedded robotic platform boards running Linux systems. These scripts follow POSIX standards for maximum portability and integration into CI tools like LAVA.
6+
Thank you for considering contributing to the **qcom-linux-testkit** project! Your contributions help improve the quality and functionality of our test suite. Please follow the guidelines below to ensure a smooth contribution process.
77

8-
## Directory Structure
8+
---
99

10-
- `Runner/`: Root test harness
11-
- `Runner/utils/`: Shared libraries like `functestlib.sh`
12-
- `Runner/init_env`: Common environment setup
13-
- `Runner/suites/`: Functional test suites organized per feature
10+
## 📋 Contribution Checklist
1411

15-
## Getting Started
12+
Before submitting a PR, please ensure the following:
1613

17-
1. Clone the repository:
14+
- [ ] **Branching**: Create your feature or fix branch from the latest `main` branch.
15+
- [ ] **Descriptive Commits**: Write clear and concise commit messages.
16+
- [ ] **ShellCheck Compliance**: Run ShellCheck on all modified shell scripts and address any warnings or errors.
17+
- [ ] **Functionality**: Verify that your changes do not break existing functionality.
18+
- [ ] **Documentation**: Update or add documentation as necessary.
19+
- [ ] **Testing**: Add or update tests to cover your changes, if applicable.
20+
21+
---
22+
23+
## 🧪 Running ShellCheck
24+
25+
We use [ShellCheck](https://www.shellcheck.net/) to analyze shell scripts for common mistakes and potential issues.
26+
27+
### Installation
28+
29+
You can install ShellCheck using your package manager:
30+
31+
- **macOS**: `brew install shellcheck`
32+
- **Ubuntu/Debian**: `sudo apt-get install shellcheck`
33+
- **Fedora**: `sudo dnf install ShellCheck`
34+
- **Arch Linux**: `sudo pacman -S shellcheck`
35+
36+
### Usage
37+
38+
To analyze a script:
39+
40+
```bash
41+
shellcheck path/to/your_script.sh
42+
```
43+
44+
Address all warnings and errors before submitting your PR. If you need to disable a specific ShellCheck warning, use:
45+
46+
```sh
47+
# shellcheck disable=SC1090
48+
```
49+
50+
---
51+
52+
## 📂 Test Suite Structure & Pseudocode Guidelines
53+
54+
Each test suite must follow the standard structure shown below and include a `run.sh` script that:
55+
56+
- Sources `init_env` and `functestlib.sh`
57+
- Sets `TESTNAME`
58+
- Finds the test directory dynamically
59+
- Logs results using `log_pass`, `log_fail`, and outputs a `.res` file
60+
61+
### Directory Structure
62+
63+
```
64+
Runner/
65+
├── suites/
66+
│ └── Kernel/
67+
│ └── FunctionalArea/
68+
│ └── baseport/
69+
│ └── Foo_Validation/
70+
│ ├── run.sh
71+
│ └── enabled_tests.list (optional)
72+
├── utils/
73+
│ ├── init_env
74+
│ └── functestlib.sh
75+
```
76+
77+
### Pseudo `run.sh` Template
78+
79+
```sh
80+
#!/bin/sh
81+
# SPDX-License-Identifier: BSD-3-Clause-Clear
82+
83+
# shellcheck disable=SC1090
84+
. "$(dirname "$0")/../../../../utils/init_env"
85+
# shellcheck disable=SC1090
86+
. "$TOOLS/functestlib.sh"
87+
88+
TESTNAME="Foo_Validation"
89+
test_path=$(find_test_case_by_name "$TESTNAME") || {
90+
log_fail "$TESTNAME : Test directory not found."
91+
echo "FAIL $TESTNAME" > "./$TESTNAME.res"
92+
exit 1
93+
}
94+
95+
cd "$test_path" || exit 1
96+
res_file="./$TESTNAME.res"
97+
rm -f "$res_file"
98+
99+
log_info "Starting $TESTNAME"
100+
101+
# Run test logic
102+
if run_some_check_or_command; then
103+
log_pass "$TESTNAME: passed"
104+
echo "PASS $TESTNAME" > "$res_file"
105+
else
106+
log_fail "$TESTNAME: failed"
107+
echo "FAIL $TESTNAME" > "$res_file"
108+
fi
109+
```
110+
111+
### `.res` File Requirements
112+
113+
Each `run.sh` **must generate** a `.res` file in the same directory:
114+
115+
- **File Name**: `<TESTNAME>.res`
116+
- **Content**:
117+
- `PASS <TESTNAME>` on success
118+
- `FAIL <TESTNAME>` on failure
119+
- `SKIP <TESTNAME>` if not applicable
120+
121+
This is essential for CI/CD to parse test outcomes.
122+
123+
### Logging Conventions
124+
125+
Use logging functions from `functestlib.sh`:
126+
```sh
127+
log_info "Preparing test"
128+
log_pass "Test completed successfully"
129+
log_fail "Test failed"
130+
log_error "Setup error"
131+
log_skip "Skipped due to condition"
132+
```
133+
134+
---
135+
136+
## 📄 Licensing
137+
138+
Ensure that all new files include the appropriate license header:
139+
140+
```sh
141+
#!/bin/sh
142+
# SPDX-License-Identifier: BSD-3-Clause-Clear
143+
```
144+
145+
---
146+
147+
## 📬 Submitting a Pull Request
148+
149+
1. **Fork** the repository and create your feature branch:
18150
```bash
19-
git clone https://github.com/qualcomm-linux/qcom-linux-testkit.git
151+
git checkout -b feature/your-feature-name
20152
```
21153

22-
2. Run test suites using:
154+
2. **Commit** your changes with clear messages:
23155
```bash
24-
./Runner/run-test.sh
156+
git commit -m "feat: add new feature"
25157
```
26158

27-
3. Ensure `init_env` and utilities are sourced using relative paths:
159+
3. **Push** to your fork:
28160
```bash
29-
. "$(dirname "$0")/../../init_env"
30-
. "$(dirname "$0")/../../utils/functestlib.sh"
161+
git push origin feature/your-feature-name
31162
```
32163

33-
## Style Guidelines
164+
4. **Open a Pull Request**: Navigate to the original repository and open a PR from your forked branch.
34165

35-
- Shell scripts must be POSIX-compliant (`#!/bin/sh`)
36-
- Avoid Bash-specific syntax
37-
- Validate using `shellcheck -x`
38-
- Use consistent format: colored output, logging, `PASS/FAIL` status
166+
Please ensure that your PR description includes:
39167

40-
## Commit and PR Guidelines
168+
- A summary of the changes made.
169+
- The reason for the changes.
170+
- Any relevant issues or discussions.
41171

42-
- One logical change per commit
43-
- Always add sign-off:
44-
```bash
45-
git commit -s -m "Add test for Bluetooth functionality"
46-
```
172+
---
47173

48-
- Mention reviewers if needed and explain validation steps
49-
- PRs should be raised against `main` unless otherwise noted
174+
## 🤝 Code of Conduct
50175

51-
## License
176+
We are committed to fostering a welcoming and respectful community. Please adhere to our [Code of Conduct](docs/CODE_OF_CONDUCT.md) in all interactions.
52177

53-
All contributions must include:
54-
```sh
55-
# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
56-
# SPDX-License-Identifier: BSD-3-Clause-Clear
178+
---
179+
180+
Thank you for contributing to **qcom-linux-testkit**!
181+
182+
183+
---
184+
185+
## 🗂️ Test Organization Guidelines
186+
187+
### Directory Placement
188+
189+
- Kernel-level tests → `Runner/suites/Kernel/FunctionalArea/`
190+
- Multimedia tests → `Runner/suites/Multimedia/`
191+
- Shared test utilities or binaries → `Runner/common/`
192+
193+
### Script Naming
194+
195+
- Main test launcher must be named `run.sh`
196+
- Helper scripts should use lowercase with underscores, e.g. `validate_cache.sh`
197+
- Avoid spaces or uppercase letters in filenames
198+
199+
---
200+
201+
## ⏱️ Test Execution & Timeout Guidelines
202+
203+
- Tests must be self-contained and deterministic
204+
- Long-running tests should support intermediate logging or status messages
205+
- Do not rely on `/tmp` or external mounts
206+
- Scripts must **fail fast** on invalid setup or missing dependencies
207+
208+
---
209+
210+
## 📄 Supported Test Artifacts
211+
212+
Optional per-suite files:
213+
- `enabled_tests.list`: whitelist of subtests to run
214+
- `*.log`: output logs from each run; should reside in the same directory
215+
- `*.res`: REQUIRED file that indicates test result in CI/CD
216+
217+
### .res File Format
218+
219+
Valid output examples:
57220
```
221+
PASS Foo_Validation
222+
FAIL Foo_Validation
223+
SKIP Foo_Validation (missing dependency)
224+
```
225+
226+
This format ensures automated tools and LAVA jobs can collect test outcomes.
227+
228+
---
229+
230+
## 🧩 Shell Compatibility
231+
232+
All scripts must run in POSIX `sh`. **Avoid Bash-only features**, including:
233+
234+
- `local` keyword (use plain assignment)
235+
- `[[ ... ]]` conditions (use `[ ... ]`)
236+
- Arrays
237+
- Bash-style arithmetic without quoting (`$(( ))`)
238+
- Here-strings or `<<<`
239+
240+
Use `#!/bin/sh` in all test scripts and validate with `ShellCheck`.
241+
242+
---
243+
244+
## 🧪 CI Integration Notes
245+
246+
Our CI/CD pipeline expects:
247+
- Each test case to create a `.res` file in the same folder
248+
- No stdout/stderr pollution unless via `log_*` functions
249+
- Proper exit codes (0 for pass, 1 for fail)
250+
251+
All logs should remain local to the suite folder, typically named `*.log`.
252+
253+
---
58254

59-
## Questions?
255+
## 🙋 Questions?
60256

61-
Open an issue or start a discussion under the GitHub Issues tab.
257+
If you're unsure where your test fits or how to structure it, open an issue or tag a maintainer in a draft PR. We're happy to help guide your first contribution.

0 commit comments

Comments
 (0)