Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
52 lines (33 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

52 lines (33 loc) · 4.27 KB
Raw

Contributing to ARENA Docs

The general Contribution Guide for all ARENA projects can be found here.

This document covers development rules and conventions specific to this repository. These rules are mandatory for all contributors, including automated/agentic coding tools.

Development Rules

1. MQTT Topics — Always Use the TOPICS Constructor

Never hardcode MQTT topic strings. All topic paths must be constructed using the local TOPICS string constructor for ease of future topics modulation. This enables future topic format refactoring without scattered string updates.

2. Dependencies — Pin All Versions

All dependencies must use exact, pegged versions (no ^, ~, or * ranges). This prevents version drift across environments and ensures reproducible builds for security.

Content Creation Directives

ARENA Documentation pages are written in markdown and placed in the content directory, except for ./index.md.

Each .md file inside content must have YAML Front Matter for navigation. The navigation details are determined by our theme. See the just-the-docs theme for more details about site navigation.

Local Development

To develop arena-docs locally:

  1. Ensure Ruby and bundler are installed.
  2. Run bundle install to install dependencies.
  3. Serve the site locally with bundle exec jekyll serve --livereload.

Code Style

  • Use standard Markdown formatting.
  • Guarantee that all front-matter contains the appropriate title and nav_order.

The arena-docs uses Release Please to automate CHANGELOG generation and semantic versioning. Your PR titles must follow Conventional Commit standards (e.g., feat:, fix:, chore:).

Caution

Never use BREAKING CHANGE in commit/PR bodies or the ! suffix on commit/PR types (e.g., feat!:, fix!:). These tokens cause release-please to automatically bump the major version. Major version increments are reserved for the maintainer's explicit decision — contributors and agents do not decide what constitutes a breaking change for semver purposes.

Important

Issue and PR References in Commit & PR Messages: Only use #NN notation in commit messages, PR titles, and PR descriptions if they correspond to actual GitHub issues or pull requests. Do not use #NN notation for internal enumerations of planning docs or triage items (e.g., use Task NN or plain text instead), as this creates erroneous links and may result in unintended automatic actions.

Important

No emoji in code comments, commit messages, or GitHub issue/PR titles and descriptions. Write plain text there. Emoji render inconsistently across editors, terminals, diffs, and generated release notes, and add nothing a plain word does not. This applies to all contributors, including automated/agentic coding tools.

Documentation pages under content/ are the exception. Small icons help a rendered page, so use them in this order of preference. First, the stored icons in assets/img/icons/, referenced as images (see the [i-...] reference definitions in content/examples.md), whenever a page shows an element of the ARENA interface. Second, for status and support matrices only, the small glyph set that survives the Markdown-to-HTML build and renders the same in every browser: the check mark, cross mark, and dash already used with a legend in content/architecture/message-validation.md. No decorative or novelty emoji anywhere: a glyph that depends on the reader's platform font does not translate.

CI & Dependency Management Conventions

  • GitHub Actions Tag SHA Pinning: All GitHub Action references in .github/workflows/ MUST be pinned to the exact commit SHA of the official release tag (e.g., uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0).
  • Inline Version Comments: The inline comment next to the SHA MUST specify the exact tag version used. This enables Dependabot to recognize the release version, generate human-readable SemVer PR titles (from X.Y.Z to A.B.C), and automatically update version comments during upgrades.