W0CHP.radio

First off, thank you for considering contributing to ChroGPS Dash! It’s people like you who make open-source tools better for the entire NTP/GNSS/precision time-keeping community.

Core Philosophy: “Zero Dependencies”

This project adheres to a strict no-dependency philosophy.

• No external CSS frameworks (Bootstrap, Tailwind, etc.).
• No external JS libraries (jQuery, Chart.js, Highcharts, etc.).
• No package managers (npm, composer, pip).
• Single-file deployment: The entire dashboard logic resides in index.php.
• Native, available APT packages: ChroGPS Dash is designed to use programs native to Debian (& Debian-like) systems for ease of deployment and for portability/repeatability.

How Can I Contribute?

Pull Requests

1. Fork the repository and create your branch from master.
2. Test locally: Ensure your changes work on a standard Debian/Ubuntu stack with chrony and gpsd.
3. Responsive Check: Verify the UI layout on both Desktop (2-column grid) and Mobile (stacked single column).
4. Theme Check: Toggle the Light/Dark mode to ensure all new elements use the correct CSS variables.
5. Submit a Pull Request with a clear description of your changes.

Reporting Bugs & Feature Requests

• Disabled and disregarded/dismissed: I only accept code contributions and bugfixes directly via Pull Requests.
• Did I make it clear that only code contributions and bugfixes are accepted? 😉

Development Guidelines

1. PHP & Graphing (The “Native SVG” Engine)

I do not use client-side charting libraries. All graphs are generated server-side using native PHP to output raw SVG XML.

• Draw Function: Use the drawGraphSVG() helper function for all charts.
• Tooltips: If you modify the charts, ensure you preserve the invisible <rect> “hit zones” that drive the JavaScript tooltips.
• Log Parsing: The dashboard reads directly from /var/log/chrony. Ensure any new parsers handle file permissions gracefully and fail silently if logs are missing.

2. JavaScript (Vanilla Only)

• No Frameworks: Use standard ES6+ JavaScript.
• AJAX Loop: The dashboard uses a single fetch('?ajax=1') loop to update all data.
  • Do not add separate polling intervals for different components.
  • All dynamic data should be returned in the single JSON response.
• DOM Manipulation: Use standard document.getElementById() or querySelector().

3. CSS & Theming

• Variables: Always use the defined CSS variables (e.g., --bg, --text, --accent, --green) to ensure full Dark/Light mode compatibility.
• Grid Layout:
  • Mobile First: The default layout is a single-column stack.
  • Desktop: I use @media (min-width: 900px) to switch to a 2-column grid.
  • Full Width Elements: Large charts should use grid-column: 1 / -1; in the desktop layout to span the full width.

4. General Development Styles and Guidelines

• Code should be well-documented/commented
• No code minification whatsoever. Code should be readable by humans so that it’s easy to develop for, and troubleshoot.
• PHP code follows PSR-12 guidelines
• JavaScript follows Modern Vanilla JS (ES6+) guidelines.
  • Indentation should be 4 spaces to maintain consistency with the PHP file structure.
• CSS and HTML are v3 and v5, respectively.
  • Indentation should be 4 spaces to maintain consistency with the PHP file structure.

5. Hardware Support

• GPS Types: When parsing gpsd data, aim to support generic NMEA devices as well as specific drivers (u-blox, SiRF).
• Baud Rates: Preserve the display format @ /dev/path (nnnn baud).

Attribution is required under the MIT License. Happy coding!