public_git
/
freenas-proxmox
mirror of https://github.com/TheGrandWazoo/freenas-proxmox.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
freenas-proxmox/CONTRIBUTING.md

4.3 KiB
Raw Permalink Blame History

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

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.

Before filing:

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.

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

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:

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

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
  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).