142 lines
4.3 KiB
Markdown
142 lines
4.3 KiB
Markdown
# Contributing to freenas-proxmox
|
|
|
|
Thank you for your interest in contributing. This document covers how to report bugs, request features, and submit code.
|
|
|
|
## Table of Contents
|
|
|
|
- [Code of Conduct](#code-of-conduct)
|
|
- [Reporting Bugs](#reporting-bugs)
|
|
- [Requesting Features](#requesting-features)
|
|
- [Development Setup](#development-setup)
|
|
- [Submitting Changes](#submitting-changes)
|
|
- [Coding Standards](#coding-standards)
|
|
- [Branch Strategy](#branch-strategy)
|
|
|
|
---
|
|
|
|
## Code of Conduct
|
|
|
|
Be respectful. This is a community project maintained in spare time. Constructive criticism is welcome; hostility is not.
|
|
|
|
---
|
|
|
|
## Reporting Bugs
|
|
|
|
Use the [bug report issue template](https://github.com/TheGrandWazoo/freenas-proxmox/issues/new?template=bug_report.md).
|
|
|
|
Before filing:
|
|
- Check existing [open and closed issues](https://github.com/TheGrandWazoo/freenas-proxmox/issues?q=is%3Aissue) for duplicates
|
|
- Reproduce the issue on the latest release if possible
|
|
|
|
**Always include:**
|
|
- Proxmox VE version (`proxmox-ve` package version)
|
|
- TrueNAS version and type (CORE / SCALE)
|
|
- Plugin version (`dpkg -l freenas-proxmox`)
|
|
- Relevant log lines from syslog (`grep -i freenas /var/log/syslog`)
|
|
- The storage configuration (redact passwords/tokens)
|
|
|
|
---
|
|
|
|
## Requesting Features
|
|
|
|
Use the [feature request issue template](https://github.com/TheGrandWazoo/freenas-proxmox/issues/new?template=feature_request.md).
|
|
|
|
Feature requests are evaluated against the project roadmap. Large changes should be discussed in an issue before a pull request is opened.
|
|
|
|
---
|
|
|
|
## Development Setup
|
|
|
|
### What You Need
|
|
|
|
- A Proxmox VE node (physical or VM) — version 8.x recommended
|
|
- A TrueNAS instance (CORE or SCALE) accessible from the Proxmox node
|
|
- Basic Perl knowledge
|
|
- `dpkg-deb` for building packages locally
|
|
|
|
### Local Build
|
|
|
|
```bash
|
|
git clone https://github.com/TheGrandWazoo/freenas-proxmox.git
|
|
cd freenas-proxmox
|
|
|
|
# Build the package (once packaging/ directory exists in v3.x)
|
|
dpkg-deb -Zgzip --build packaging freenas-proxmox_dev_all.deb
|
|
|
|
# Install locally for testing
|
|
dpkg -i freenas-proxmox_dev_all.deb
|
|
```
|
|
|
|
### Testing Changes to FreeNAS.pm
|
|
|
|
You can copy the Perl module directly to the Proxmox node for quick iteration without rebuilding the package:
|
|
|
|
```bash
|
|
scp perl5/PVE/Storage/LunCmd/FreeNAS.pm \
|
|
root@your-proxmox-node:/usr/share/perl5/PVE/Storage/LunCmd/FreeNAS.pm
|
|
|
|
# Restart PVE services on the node
|
|
ssh root@your-proxmox-node "pvedaemon restart && pveproxy restart"
|
|
```
|
|
|
|
### Checking Perl Syntax
|
|
|
|
```bash
|
|
perl -c perl5/PVE/Storage/LunCmd/FreeNAS.pm
|
|
perl -c perl5/PVE/Storage/Custom/TrueNASPlugin.pm
|
|
```
|
|
|
|
---
|
|
|
|
## Submitting Changes
|
|
|
|
1. Fork the repository
|
|
2. Create a branch from `master`: `git checkout -b feature/your-description`
|
|
3. Make your changes — see [Coding Standards](#coding-standards)
|
|
4. Test on a real Proxmox + TrueNAS setup if possible
|
|
5. Open a pull request against `master`
|
|
|
|
Pull requests should:
|
|
- Have a clear description of what changed and why
|
|
- Reference any related issues (`Fixes #123`)
|
|
- Not include unrelated changes
|
|
|
|
---
|
|
|
|
## Coding Standards
|
|
|
|
### Perl
|
|
|
|
- `use strict` and `use warnings` in all modules
|
|
- Use `syslog("info", ...)` for normal operation logging, `syslog("err", ...)` for errors
|
|
- Include the caller context in log lines: `(caller(0))[3] . " : message"`
|
|
- All external API calls wrapped in error handling with cleanup on failure
|
|
- No `eval $variable` patterns — use explicit substitution maps
|
|
- Prefer `LWP::UserAgent` over `REST::Client` for new code
|
|
|
|
### Shell (postinst/postrm)
|
|
|
|
- `set -e` at the top of all scripts
|
|
- Log to a file rather than swallowing output with `&> /dev/null`
|
|
- Use shellcheck-clean scripts (`shellcheck packaging/DEBIAN/postinst`)
|
|
- Idempotent operations — scripts must be safe to run multiple times
|
|
|
|
### Patches
|
|
|
|
- Patches live in `stable-N/` directories where N is the Proxmox VE major version
|
|
- Always include both `.orig` and `.patch` for reference
|
|
- Test with `patch --dry-run` before committing
|
|
- Use `--ignore-whitespace` in patch commands
|
|
|
|
---
|
|
|
|
## Branch Strategy
|
|
|
|
| Branch | Purpose | Builds to |
|
|
|--------|---------|-----------|
|
|
| `master` | Main development branch | Beta/testing apt channel |
|
|
| `feature/*` | Feature branches | Alpha apt channel |
|
|
| `stable` / tagged releases | Release-ready code | Stable apt channel |
|
|
|
|
Tag releases as `vMAJOR.MINOR.PATCH` (e.g., `v3.0.0`).
|