Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (62 loc) · 4.28 KB

CONTRIBUTING.md

File metadata and controls

98 lines (62 loc) · 4.28 KB
Raw

How to contribute

Did you find a bug?

  • Ensure the bug was not already reported by searching on GitHub under Issues.

  • If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or a clear explanation demonstrating the expected behavior that is not occurring.

Did you write a patch that fixes a bug?

  • Make sure there is a GitHub issue for the patch you are writing.

  • Open a new GitHub pull request with the patch.

  • Ensure the PR description clearly describes the problem and solution. Include the relevant issue number.

In case your specific project differs too much from the reference project in this repository, use the PLCopen XML to export the specific artifacts including the fix and attach them to the relevant GitHub issue.

Do you intend to add a new feature or change an existing one?

  • Suggest your change/feature in the Gitter chat and start writing code.

  • Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports, fixes and milestone tracking.

Do you have questions about the source code?

  • Ask any question about how to use the source code in the Gitter chat.

What do I name it?

  • Read the coding style. It decides the name of every object and every variable, so there is nothing to weigh up: objects are PREFIX_ + SCREAMING_SNAKE (FB_, E_, ST_, I_, A_, GVL_, PRG_, F_) and variables are a type prefix plus PascalCase (bStartup, sFriendlyName, pMqttPublishQueue).

  • Two details that catch people: b is BOOL and by is BYTE, following the CODESYS guide rather than TwinCAT habit — and the MQTT_DISCOVERY_* structs are exempt, because their member names are published as Home Assistant discovery keys.

Merge request (pull request)

GIT side

  1. Create your own fork (if you haven't already).
  2. Don't change the default .project for your own config.
  3. Optional: create a branch.
  4. Code.
  5. Prepare for export, see below.
  6. Add documentation in the markdown files.
  7. Create a merge/pull request from your repo to this one.

Prepare for export

The export is a PLCopen XML file that others import to pick up your changes. The .project is upgraded with the new changes too, so it stays a basic version for newcomers.

  1. Save the .project file

    • Make sure the original project is unmodified
    • Save with another name.

  2. Run export (from your modified project)

    • Export all files except configs

      So no GVL_* lists, PRG's and GVL_PERSISTENT

    • You can export Variables/Library if you see fit

    • Export as PLCopen XML to Exports\PLCopen.xml

  3. Open the original .project. Keep your config out.

    • Follow this guide to update your blocks

    • Add 1 example of the new function block/methods to the POU

    • Document the new function block/methods in the POU!

Function block documentation

The block diagrams, interface tables and method tables in docs/FunctionBlocks/*.md are generated from src/Exports/PLCopen.xml, as is the GVL_MQTT listing in MQTT_General.md. Don't write them by hand and don't edit between the <!-- fb-badge -->, <!-- fb-interface --> or <!-- gvl --> markers — descriptions inside those regions are preserved across regenerations, everything else is rebuilt from the export.

Adding a function block? Scaffold its page with --new FB_NAME rather than copying an existing one.

After re-exporting the PLCopen XML, regenerate them from the repo root:

python3 .claude/skills/update-fb-docs/scripts/gen_fb_docs.py

Add --check to verify the docs still match the export without writing anything. Wiring diagrams are still hand-drawn and live in docs/_drawio/.