Skip to content

Commit ba05a16

Browse files
srpatchasrpatcha
committed
docs: add full contributing guide with prerequisites, cross-compile, test suites, coding standards
1 parent 6cf9059 commit ba05a16

1 file changed

Lines changed: 210 additions & 119 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 210 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,210 @@
1-
# Contributing to eboot
2-
3-
Thank you for your interest in contributing to eBootloader!
4-
5-
## Getting Started
6-
7-
1. Fork the repository
8-
2. Create a feature branch: `git checkout -b feat/my-feature`
9-
3. Make your changes
10-
4. Run the build and tests locally
11-
5. Submit a pull request
12-
13-
## Development Setup
14-
15-
```bash
16-
git clone https://github.com/embeddedos-org/eboot.git
17-
cd eboot
18-
cmake -B build -DEBLDR_BUILD_TESTS=ON
19-
cmake --build build
20-
ctest --test-dir build --output-on-failure
21-
```
22-
23-
For config generation testing:
24-
```bash
25-
pip install -r requirements.txt
26-
python scripts/generate_config.py configs/example_boot.yaml /tmp/generated/
27-
```
28-
29-
## CI Requirements
30-
31-
All pull requests must pass the following CI checks before merging:
32-
33-
### Required Status Checks
34-
35-
| Check | Platform | What It Validates |
36-
|---|---|---|
37-
| **Build (ubuntu-latest)** | Linux | GCC build + all 7 unit tests |
38-
| **Build (windows-latest)** | Windows | MSVC build + all 7 unit tests |
39-
| **Build (macos-latest)** | macOS | Clang build + all 7 unit tests |
40-
| **Config Generation** | Linux | `generate_config.py` produces valid headers and linker scripts |
41-
42-
### How to Verify Locally
43-
44-
Before submitting a PR, ensure all checks pass:
45-
46-
```bash
47-
# 1. Build + test on your host
48-
cmake -B build -DEBLDR_BUILD_TESTS=ON
49-
cmake --build build --config Release
50-
ctest --test-dir build --output-on-failure -C Release
51-
52-
# 2. Config generation
53-
pip install -r requirements.txt
54-
python scripts/generate_config.py configs/example_boot.yaml /tmp/out/
55-
test -f /tmp/out/eboot_generated_layout.h
56-
test -f /tmp/out/eboot_generated_memory.ld
57-
```
58-
59-
### Nightly Regression (Informational)
60-
61-
The nightly workflow runs additional cross-compilation checks that are not required for PRs but are monitored for regressions:
62-
63-
- Cross-compile for AArch64 Linux (`aarch64-linux-gnu-gcc`)
64-
- Cross-compile for RISC-V 64 (`riscv64-linux-gnu-gcc`)
65-
- Cross-compile for ARM Cortex-M (`arm-none-eabi-gcc`)
66-
67-
## Code Guidelines
68-
69-
### C Style
70-
71-
- **Standard:** C11 (`-std=c11`)
72-
- **Warnings:** `-Wall -Wextra` must compile clean (zero warnings)
73-
- **Platform guards:** All platform-specific code must be guarded:
74-
- `#if defined(__APPLE__)` for macOS
75-
- `#if defined(_MSC_VER)` for MSVC/Windows
76-
- `#if defined(__GNUC__) || defined(__clang__)` for GCC/Clang
77-
- `#if defined(__ARM_ARCH)` for ARM-specific code
78-
- **No `printf` in production paths** — use `eos_hal_uart_send()` for output
79-
- **Include guards:** Use `#ifndef HEADER_NAME_H` / `#define` / `#endif`
80-
- **Types:** Use `<stdint.h>` types (`uint32_t`, `int8_t`, etc.)
81-
82-
### Commit Messages
83-
84-
Follow [Conventional Commits](https://www.conventionalcommits.org/):
85-
86-
```
87-
feat: add SPI transport for firmware update
88-
fix: bootctl CRC calculation on big-endian targets
89-
docs: update board porting guide
90-
ci: add ARM Cortex-M cross-compilation to nightly
91-
chore: bump version to 0.4.0
92-
```
93-
94-
### Pull Request Checklist
95-
96-
- [ ] Code compiles with zero warnings on GCC, Clang, and MSVC
97-
- [ ] All existing tests pass
98-
- [ ] New features include unit tests in `tests/unit/`
99-
- [ ] Platform-specific code has `#ifdef` guards for all 3 OS targets
100-
- [ ] No hardcoded paths (use platform abstractions)
101-
- [ ] Commit messages follow conventional commits format
102-
103-
## Adding a New Board Port
104-
105-
1. Create `boards/<name>/board_<name>.c` implementing `eos_board_ops_t`
106-
2. Create `boards/<name>/board_<name>.h` with memory map constants
107-
3. Add the board to `CMakeLists.txt` via `eboot_add_board()`
108-
4. Optionally add linker scripts (`<name>_stage0.ld`, `<name>_stage1.ld`)
109-
5. Add the board name to the help text in `CMakeLists.txt`
110-
111-
## Reporting Issues
112-
113-
- Use GitHub Issues with the appropriate label (`bug`, `enhancement`, `question`)
114-
- Include: OS, compiler version, board target, and full error output
115-
- For build failures: attach the full CMake configure + build log
116-
117-
## License
118-
119-
By contributing, you agree that your contributions will be licensed under the MIT License.
1+
# Contributing to eboot
2+
3+
Thank you for your interest in contributing to eBootloader!
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Create a feature branch: `git checkout -b feat/my-feature`
9+
3. Make your changes
10+
4. Run the build and tests locally
11+
5. Submit a pull request
12+
13+
## Prerequisites
14+
15+
| Tool | Minimum Version | Purpose |
16+
|---|---|---|
17+
| **CMake** | 3.16+ | Build system |
18+
| **GCC / Clang / MSVC** | GCC 10+, Clang 12+, MSVC 2019+ | C11 compiler |
19+
| **Python** | 3.8+ | Config generation scripts |
20+
| **PyYAML** | 6.0+ | `pip install -r requirements.txt` |
21+
| **arm-none-eabi-gcc** | 10+ | *(optional)* ARM Cortex-M cross-compilation |
22+
| **aarch64-linux-gnu-gcc** | 10+ | *(optional)* AArch64 cross-compilation |
23+
| **riscv64-linux-gnu-gcc** | 10+ | *(optional)* RISC-V 64 cross-compilation |
24+
25+
## Development Setup
26+
27+
### Native Build (Host)
28+
29+
```bash
30+
git clone https://github.com/embeddedos-org/eboot.git
31+
cd eboot
32+
cmake -B build -DEBLDR_BUILD_TESTS=ON
33+
cmake --build build
34+
ctest --test-dir build --output-on-failure
35+
```
36+
37+
### Cross-Compilation
38+
39+
```bash
40+
# ARM Cortex-M (bare-metal)
41+
cmake -B build-arm -DEBLDR_BOARD=stm32f4 \
42+
-DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake
43+
cmake --build build-arm
44+
45+
# AArch64 Linux (e.g. RPi4)
46+
cmake -B build-aarch64 -DEBLDR_BOARD=rpi4 \
47+
-DCMAKE_TOOLCHAIN_FILE=toolchains/aarch64-linux-gnu.cmake
48+
cmake --build build-aarch64
49+
50+
# RISC-V 64
51+
cmake -B build-riscv -DEBLDR_BOARD=riscv64_virt \
52+
-DCMAKE_TOOLCHAIN_FILE=toolchains/riscv64-linux-gnu.cmake
53+
cmake --build build-riscv
54+
```
55+
56+
### Config Generation Testing
57+
58+
```bash
59+
pip install -r requirements.txt
60+
python scripts/generate_config.py configs/example_boot.yaml /tmp/generated/
61+
```
62+
63+
## Test Suites
64+
65+
eboot includes 7 unit test suites that run natively on the host:
66+
67+
| Test | Covers |
68+
|---|---|
69+
| `test_bootctl` | Boot control block save/load, CRC, rollback |
70+
| `test_crypto` | SHA-256 against known vectors |
71+
| `test_device_table` | Device table create, add, validate |
72+
| `test_runtime_svc` | Runtime variable get/set/delete |
73+
| `test_board_config` | Pin/memory/IRQ config lookup |
74+
| `test_multicore` | Core state management, SMP/AMP init |
75+
| `test_board_registry` | Board register, find, activate |
76+
77+
Run all tests:
78+
79+
```bash
80+
cmake -B build -DEBLDR_BUILD_TESTS=ON
81+
cmake --build build --config Release
82+
ctest --test-dir build --output-on-failure -C Release
83+
```
84+
85+
## CI Requirements
86+
87+
All pull requests must pass the following CI checks before merging:
88+
89+
### Required Status Checks
90+
91+
| Check | Platform | What It Validates |
92+
|---|---|---|
93+
| **Build (ubuntu-latest)** | Linux | GCC build + all 7 unit tests |
94+
| **Build (windows-latest)** | Windows | MSVC build + all 7 unit tests |
95+
| **Build (macos-latest)** | macOS | Clang build + all 7 unit tests |
96+
| **Config Generation** | Linux | `generate_config.py` produces valid headers and linker scripts |
97+
98+
### How to Verify Locally
99+
100+
Before submitting a PR, ensure all checks pass:
101+
102+
```bash
103+
# 1. Build + test on your host
104+
cmake -B build -DEBLDR_BUILD_TESTS=ON
105+
cmake --build build --config Release
106+
ctest --test-dir build --output-on-failure -C Release
107+
108+
# 2. Config generation
109+
pip install -r requirements.txt
110+
python scripts/generate_config.py configs/example_boot.yaml /tmp/out/
111+
test -f /tmp/out/eboot_generated_layout.h
112+
test -f /tmp/out/eboot_generated_memory.ld
113+
```
114+
115+
### Nightly Regression (Informational)
116+
117+
The nightly workflow runs additional cross-compilation checks that are not required for PRs but are monitored for regressions:
118+
119+
- Cross-compile for AArch64 Linux (`aarch64-linux-gnu-gcc`)
120+
- Cross-compile for RISC-V 64 (`riscv64-linux-gnu-gcc`)
121+
- Cross-compile for ARM Cortex-M (`arm-none-eabi-gcc`)
122+
123+
## Code Guidelines
124+
125+
### C Style
126+
127+
- **Standard:** C11 (`-std=c11`)
128+
- **Warnings:** `-Wall -Wextra` must compile clean (zero warnings)
129+
- **Platform guards:** All platform-specific code must be guarded:
130+
- `#if defined(__APPLE__)` for macOS
131+
- `#if defined(_MSC_VER)` for MSVC/Windows
132+
- `#if defined(__GNUC__) || defined(__clang__)` for GCC/Clang
133+
- `#if defined(__ARM_ARCH)` for ARM-specific code
134+
- **No `printf` in production paths** — use `eos_hal_uart_send()` for output
135+
- **Include guards:** Use `#ifndef HEADER_NAME_H` / `#define` / `#endif`
136+
- **Types:** Use `<stdint.h>` types (`uint32_t`, `int8_t`, etc.)
137+
- **C++ compatibility:** All public headers must have `extern "C"` guards
138+
139+
### Commit Messages
140+
141+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
142+
143+
```
144+
feat: add SPI transport for firmware update
145+
fix: bootctl CRC calculation on big-endian targets
146+
docs: update board porting guide
147+
ci: add ARM Cortex-M cross-compilation to nightly
148+
chore: bump version to 0.4.0
149+
```
150+
151+
### Pull Request Checklist
152+
153+
- [ ] Code compiles with zero warnings on GCC, Clang, and MSVC
154+
- [ ] All existing tests pass
155+
- [ ] New features include unit tests in `tests/unit/`
156+
- [ ] Platform-specific code has `#ifdef` guards for all 3 OS targets
157+
- [ ] No hardcoded paths (use platform abstractions)
158+
- [ ] Commit messages follow conventional commits format
159+
160+
## Adding a New Board Port
161+
162+
1. Create `boards/<name>/board_<name>.c` implementing `eos_board_ops_t`
163+
2. Create `boards/<name>/board_<name>.h` with memory map constants
164+
3. Add the board to `CMakeLists.txt` via `eboot_add_board()`
165+
4. Optionally add linker scripts (`<name>_stage0.ld`, `<name>_stage1.ld`)
166+
5. Add the board name to the help text in `CMakeLists.txt`
167+
168+
## Reporting Issues
169+
170+
- Use GitHub Issues with the appropriate label (`bug`, `enhancement`, `question`)
171+
- Include: OS, compiler version, board target, and full error output
172+
- For build failures: attach the full CMake configure + build log
173+
174+
## License
175+
176+
By contributing, you agree that your contributions will be licensed under the MIT License.
177+
```
178+
feat: add SPI transport for firmware update
179+
fix: bootctl CRC calculation on big-endian targets
180+
docs: update board porting guide
181+
ci: add ARM Cortex-M cross-compilation to nightly
182+
chore: bump version to 0.4.0
183+
```
184+
185+
### Pull Request Checklist
186+
187+
- [ ] Code compiles with zero warnings on GCC, Clang, and MSVC
188+
- [ ] All existing tests pass
189+
- [ ] New features include unit tests in `tests/unit/`
190+
- [ ] Platform-specific code has `#ifdef` guards for all 3 OS targets
191+
- [ ] No hardcoded paths (use platform abstractions)
192+
- [ ] Commit messages follow conventional commits format
193+
194+
## Adding a New Board Port
195+
196+
1. Create `boards/<name>/board_<name>.c` implementing `eos_board_ops_t`
197+
2. Create `boards/<name>/board_<name>.h` with memory map constants
198+
3. Add the board to `CMakeLists.txt` via `eboot_add_board()`
199+
4. Optionally add linker scripts (`<name>_stage0.ld`, `<name>_stage1.ld`)
200+
5. Add the board name to the help text in `CMakeLists.txt`
201+
202+
## Reporting Issues
203+
204+
- Use GitHub Issues with the appropriate label (`bug`, `enhancement`, `question`)
205+
- Include: OS, compiler version, board target, and full error output
206+
- For build failures: attach the full CMake configure + build log
207+
208+
## License
209+
210+
By contributing, you agree that your contributions will be licensed under the MIT License.

0 commit comments

Comments
 (0)