Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (92 loc) · 4.36 KB

CONTRIBUTING.md

File metadata and controls

119 lines (92 loc) · 4.36 KB

File: CONTRIBUTING.md

Contributing to STAG (Solar Thermoacoustic “Bagpipe” Generator)

This repository is designed to be engineer-readable and test-falsifiable. Contributions are welcome only if they improve clarity, measurability, safety, and buildability.

0) License reminder (read first)

This repo is under an Evaluation-Only License (No Commercial Use).
By contributing, you agree your contribution is provided under the same license terms for evaluation purposes.
If you need commercial rights, do not contribute—contact the repository owner instead.

1) What contributions are most valuable

High-value contributions

  • Tightening assumptions, limits, and failure modes
  • Better instrumentation plans (sensor selection, placement, calibration discipline)
  • Thermal design improvements (absorber/HHX/CHX loss reductions) with buildable BOM
  • Resonator/regenerator sizing methodology with clear parameters
  • Transducer coupling and impedance-matching guidance
  • Test protocols with pass/fail metrics and data templates

Low-value / not accepted

  • “It should work because…” statements without measurement or defensible modeling
  • Exotic physics claims (ether, vacuum energy, “over unity”)
  • Unbounded performance claims with no energy balance

2) Ground rules (how we keep this serious)

A) No hand-waving

If you propose an improvement, include at least one of:

  • a measurable prediction (what metric changes, and how we would measure it),
  • a simplified model (0D/1D) with stated assumptions,
  • or a clear test that would falsify the idea quickly.

B) Energy balance discipline

Any output claim must reference:

  • solar/thermal input estimate (with uncertainty),
  • key temperatures (hot/cold),
  • electrical power into known load,
  • and the major loss paths.

C) Safety is not optional

Any proposed build/test changes must consider:

  • concentrated solar hazard controls,
  • hot-surface containment/guards,
  • pressure safety (ratings + relief),
  • electrical protection (fusing/clamps/dump load).

3) Repo structure conventions

  • docs/ — architecture, requirements, claims/limits, glossary, theory notes
  • design/ — geometry, interfaces, drawings, materials assumptions
  • bom/ — parts lists + sourcing tiers + alternator/instrumentation options
  • models/ — calculators, parameter sweeps, sanity checks (transparent, not magic)
  • test/ — test plans, calibration steps, data templates

Keep additions in the correct folder and keep filenames descriptive.

4) Documentation style (engineer-readable)

  • Use plain language first, then equations/derivations
  • Define variables and units (SI preferred)
  • State assumptions explicitly (temperature ranges, pressures, gas choice)
  • Separate:
    • What is measured
    • What is estimated
    • What is assumed

If something is a hypothesis, label it a hypothesis.

5) Data standards (when contributing test results)

If you contribute test data, include:

  • test date/time and environment (ambient temp, wind notes if outdoors)
  • sensor models + calibration notes (or at minimum datasheet accuracy)
  • time-series where possible (don’t just report one number)
  • load conditions (exact resistance or load bank settings)
  • photos or diagrams of sensor placement (if you can)

Preferred file formats

  • CSV for time series (.csv)
  • Markdown for run summaries (.md)
  • Avoid proprietary formats unless accompanied by exported CSV.

6) Proposed workflow for changes

  1. Open an issue describing the change and the rationale
  2. Include what you expect to improve (metric)
  3. Include how to test/falsify it
  4. Submit a PR referencing the issue

7) Pull Request checklist (required)

Your PR should include:

  • Clear description of change and why it matters
  • Any new assumptions explicitly stated
  • Any safety impact assessed (even “no change”)
  • If performance-related: a measurement plan or model update
  • No commercial usage language or instructions that violate the license

8) Attribution & citations

If you reference external concepts:

  • cite papers, textbooks, or vendor datasheets
  • do NOT paste copyrighted text
  • do NOT import third-party code unless its license permits it and you include attribution

9) Contact

For commercial licensing, evaluation partnerships, or consulting engagements, contact the repository owner (Bryce Lovell).