Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
524 lines (386 loc) · 11.1 KB

CONTRIBUTING.md

File metadata and controls

524 lines (386 loc) · 11.1 KB

Contributing to k3s-device

Thank you for your interest in contributing to the k3s-device platform! This document provides guidelines for contributing code, documentation, and other improvements.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Ways to Contribute

1. Add a New Board Support Package (BSP)

The most impactful contribution is adding support for a new embedded device.

Prerequisites:

  • Hardware available for testing
  • Familiarity with device's SDK/toolchain
  • Understanding of networking and embedded systems

Process:

  1. Read /docs/adding-bsp/PORTING_GUIDE.md
  2. Study reference implementation: /implementations/rp2040-pico-c/
  3. Follow checklist: /docs/adding-bsp/CHECKLIST.md
  4. Create PR with complete BSP implementation

Example BSPs Needed:

  • ESP32 (C with ESP-IDF)
  • ESP32-C3 (RISC-V)
  • Arduino boards (C++)
  • MicroPython on Pico/ESP32
  • STM32 boards
  • Nordic nRF52 series

2. Improve Existing BSPs

Enhance current implementations:

  • Optimize memory usage
  • Improve error handling
  • Add features (Watch API, Events, etc.)
  • Fix bugs
  • Improve documentation

3. Platform Infrastructure

Contribute to shared infrastructure:

  • Device Operator (automatic provisioning)
  • ECI registry
  • Firmware repository
  • Metrics aggregation
  • Web dashboard

4. Embedded Container Images (ECIs)

Create workloads for embedded devices:

  • Example applications (blink, sensor-reader, etc.)
  • Production-ready ECIs (monitoring, control, etc.)
  • Architecture-specific optimizations
  • ECI development tools

5. Documentation

Improve or create documentation:

  • Tutorials and guides
  • Architecture explanations
  • Troubleshooting guides
  • Video walkthroughs
  • Translations

6. Testing

Expand test coverage:

  • Unit tests for firmware components
  • Integration tests for kubelet protocol
  • Hardware-in-the-loop testing
  • Performance benchmarking

Getting Started

1. Fork and Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/k3s-device.git
cd k3s-device

# Add upstream remote
git remote add upstream https://github.com/mak3r/k3s-device.git

2. Set Up Environment

# Run interactive setup
./setup-env.sh

# This generates CLAUDE.md with your environment

3. Create a Branch

# Create feature branch
git checkout -b feature/your-feature-name

# Or for BSP:
git checkout -b bsp/board-name-language

4. Make Changes

Follow coding standards and guidelines (see below).

5. Test Your Changes

For Firmware Changes:

cd implementations/{your-bsp}
mkdir build && cd build
cmake ..
make -j4

# Flash to hardware and test
cp firmware.uf2 /run/media/$USER/DEVICE/

For Infrastructure Changes:

# Apply to test cluster
kubectl apply -f infrastructure/manifests/

# Verify functionality
kubectl get pods -n kube-system -l app=pico-proxy

6. Commit Your Changes

git add .
git commit -s -m "Brief description of changes

Detailed explanation of what changed and why.

Signed-off-by: Your Name <your.email@example.com>"

Note: The -s flag adds a Signed-off-by line (DCO requirement).

7. Push and Create PR

git push origin feature/your-feature-name

Go to GitHub and create a Pull Request from your branch to mak3r/k3s-device:main.

Pull Request Guidelines

PR Title

Use conventional commit format:

feat: Add ESP32 BSP implementation
fix: Correct memory leak in HTTP client
docs: Update porting guide with RISC-V details
refactor: Simplify JSON serialization
test: Add integration tests for node registration

Prefixes:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks
  • perf: Performance improvements

PR Description

Include:

## Description
Brief summary of changes.

## Motivation
Why are these changes needed?

## Changes Made
- Bullet point list of changes
- Be specific

## Testing
- How did you test these changes?
- Hardware used
- Test results

## Screenshots/Videos (if applicable)
Attach media showing functionality.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review of code performed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Commit messages are clear
- [ ] Signed-off commits (DCO)

Review Process

  1. Automated Checks: CI runs (linting, build tests)
  2. Maintainer Review: Code review by project maintainers
  3. Testing: Maintainer may test on real hardware
  4. Approval: PR approved and merged

Timeline: Expect initial review within 1 week. Complex PRs may take longer.

Coding Standards

Firmware Code (C)

Style:

  • 4-space indentation
  • K&R brace style
  • Descriptive variable names
  • Comments for non-obvious logic

Example:

// Good
int k3s_client_register_node(const char *node_name) {
    if (!node_name || strlen(node_name) == 0) {
        printf("ERROR: Invalid node name\n");
        return -1;
    }

    // Build JSON payload
    char json[2048];
    build_node_json(json, sizeof(json), node_name);

    // Send POST request
    return http_post("/api/v1/nodes", json);
}

// Bad
int reg(char*n){if(!n)return -1;char j[2048];bld(j,sizeof(j),n);return post("/api/v1/nodes",j);}

Memory:

  • Use heap for buffers >1 KB
  • Always check malloc() return value
  • Free memory in all code paths (including errors)
  • Document ownership (who frees memory)

Error Handling:

  • Return 0 on success, -1 on error
  • Log errors with printf() or similar
  • Don't crash on recoverable errors
  • Clean up resources before returning error

Python Code (Provisioning)

Style:

  • Follow PEP 8
  • 4-space indentation
  • Type hints where beneficial
  • Docstrings for functions

Example:

def flash_firmware(device_path: str, firmware_path: str) -> bool:
    """
    Flash firmware to device.

    Args:
        device_path: Path to device (e.g., "/dev/ttyACM0")
        firmware_path: Path to firmware binary

    Returns:
        True if successful, False otherwise
    """
    if not os.path.exists(firmware_path):
        logger.error(f"Firmware not found: {firmware_path}")
        return False

    try:
        with open(firmware_path, 'rb') as f:
            firmware_data = f.read()

        # Flash logic here
        return True

    except Exception as e:
        logger.exception(f"Flash failed: {e}")
        return False

Kubernetes Manifests (YAML)

Style:

  • 2-space indentation
  • Comments for non-obvious configuration
  • Use namespaces (not default)
  • Resource limits specified

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: pico-firmware-v1.0.0
  namespace: embedded-system
  labels:
    app: pico-provisioner
    version: v1.0.0
data:
  # Firmware binary (base64-encoded)
  firmware.uf2: |
    <base64-data>

Documentation (Markdown)

Style:

  • Clear headings hierarchy
  • Code blocks with language tags
  • Examples for concepts
  • Links to related docs

Example:

# Topic Name

Brief introduction.

## Subtopic

Explanation of subtopic.

### Example

```bash
# Command with comment
kubectl get nodes
```

**Output**:
```
NAME         STATUS   ROLES    AGE   VERSION
pico-node-1  Ready    <none>   5m    v1.28.0-embedded
```

See [Related Doc](./path/to/doc.md) for more details.

Security Guidelines

Never Commit

  • Credentials: WiFi passwords, k8s tokens, API keys
  • CLAUDE.md: Environment-specific, generated file
  • config_local.h: Device-specific credentials
  • Private keys: .key, .pem files

These are all in .gitignore. Double-check before committing.

Handling Secrets

  • Store in Kubernetes Secrets
  • Mount read-only in pods
  • Never log credentials
  • Use environment variables, not hardcoded values

Code Review Focus

  • Check for credential leaks
  • Verify input validation
  • Ensure proper error handling
  • Look for buffer overflows

Testing Requirements

Before Submitting PR

  • Code compiles without errors
  • Code runs on real hardware (for BSPs)
  • No memory leaks (run for extended period)
  • Documentation updated
  • Tests pass (if applicable)

BSP-Specific Testing

For new BSPs, test:

  1. ✅ WiFi/network connection
  2. ✅ Node registration
  3. ✅ Heartbeat/status updates
  4. ✅ ConfigMap polling
  5. ✅ Memory usage within limits
  6. ✅ Runs for 24+ hours without crashes

Documentation Requirements

Code Documentation

  • Public functions: Docstrings/comments
  • Complex algorithms: Explanation comments
  • Magic numbers: Named constants with comments

User-Facing Documentation

For new BSPs, include:

  • README.md (overview, quick start)
  • docs/BUILDING.md (build instructions)
  • docs/FLASHING.md (how to flash)
  • docs/HARDWARE.md (hardware specs, limitations)

Platform Documentation

If your PR affects platform architecture:

  • Update /docs/architecture/OVERVIEW.md
  • Update relevant /specs/*.md files
  • Update root README.md if needed

Communication

GitHub Issues

Use issues for:

  • Bug reports
  • Feature requests
  • Architecture discussions
  • Questions

Issue Template (for bugs):

**Describe the bug**
Clear description of what's wrong.

**To Reproduce**
Steps to reproduce:
1. Flash firmware...
2. Connect to network...
3. See error...

**Expected behavior**
What should happen.

**Environment**
- BSP: rp2040-pico-c
- Firmware version: v1.0.0
- k3s version: v1.28.3+k3s1
- Hardware: Raspberry Pi Pico W

**Logs**

[paste logs here]


**Additional context**
Any other relevant information.

GitHub Discussions

Use discussions for:

  • General questions
  • Architecture proposals
  • Community showcases
  • Announcements

Real-Time Chat

(Future: Discord/Slack channel)

Versioning

This project follows Semantic Versioning:

  • Major (1.0.0): Breaking changes
  • Minor (0.1.0): New features, backward compatible
  • Patch (0.0.1): Bug fixes, backward compatible

BSPs may have independent versions from platform.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0, the same license as the project.

All commits must be signed off (DCO):

git commit -s -m "Your commit message"

This adds:

Signed-off-by: Your Name <your.email@example.com>

This certifies you have the right to contribute the code.

Recognition

Contributors are recognized in:

  • GitHub contributors page
  • Release notes
  • Platform documentation (for significant contributions)

Questions?

  • GitHub Issues: General questions
  • GitHub Discussions: Architecture, design discussions
  • Email: (TBD: project maintainer email)

Resources

Thank you for contributing to k3s-device! Your efforts help bring Kubernetes to embedded devices everywhere. 🚀