Skip to content

Latest commit

 

History

History
87 lines (58 loc) · 5.15 KB

CONTRIBUTING.md

File metadata and controls

87 lines (58 loc) · 5.15 KB

🚧 Contributing to Enapter Device Blueprints

We welcome any contributions when it comes to integrating new devices into the system, whether it's development efforts or testing the blueprints on your hardware.

Feel free to:

  • 🐛 Report an issue
  • 📖 Improve documentation
  • 👨‍💻 Contribute to the code
  • 🔌 Provide remote access to your hardware
  • 🎥 Create review or tutorial video on Youtube

Feel free to open discussion in Discord or GitHub

Go through the tutorial to learn about the blueprint concept and development workflow.

Note About Dot-Fields

manifest.yml is validated against the specification, although not every aspect of the manifest is ready to be fixed in the specification. Some in-progress features are backed by YAML fields that start with a dot (e.g. .cloud). These fields are not documented and ignored in the manifest validation. When the feature is ready, the field will be moved into the main manifest body, and the blueprints will be updated.

Writing Blueprint README

Please follow this simple checklist for every blueprint README file:

  • Level 1 header should contain vendor and full model or product family.
  • Intro paragraph should briefly describe the device.
  • Make sure that blueprint's use case is clear.
  • Some blueprints may require physical connection schematics. You can add it as a picture to the README file or as a link to a PDF file. Place the file into the .assets blueprint subdirectory (example).
  • List the hardware needed for the physical connection. This may be an Enapter UCM model, communication interface converter, etc.
  • Device pictures and vendor logos are always welcome, but we ask you to respect the author of said pictures and to follow copyright and licencing guidelines.
  • References should be given to the device vendor page, manual, API documentation, etc.

Linters and Formatters

Blueprint files are validated using several linters:

The configuration can be found in .yamllint.yml, .luacheckrc, .markdownlint.yml and .stylua.toml files respectively.

Run the linters locally before creating a pull request:

luacheck .
yamllint .
markdownlint .
stylua --check .

⚠️ Some of the existing files have not been auto-formatted yet, so stylua --check . will fail. Changes introduced by auto-formatting require review, which is still in progress.

To automatically run the checks before each commit, consider enabling pre-commit hooks:

pre-commit install

Lua Codestyle

Lua code is expected to be autoformatted with StyLua.

Here are some conventions besides that enforced by the auto-formatter:

  • Document with LDoc.
  • Use snake_case for variables and functions.
  • Use CamelCase for OOP class names.
  • Use UPPER_CASE for constants. Put top-level constants at the beginning of the file.
  • Use is_ when naming boolean functions, e.g. is_between().
  • Typecheck in critical places (assert(type(myvar) == 'string')).

Some more coding conventions are available in the LuaRocks style guide.

Community and Support

  •   Join our Discord community!
  •   Take a look on our documentation.
  •   Open thread on GitHub!
  •   Support us on ProducHunt with review and upvote!

License and Authorship

Blueprints in the marketplace should be licensed under the MIT license. Please add license: MIT in your manifest.yml.

Also you can specify authorship and support information via author, contributors and support fields.