OpenWISP-Website is the source repository for the OpenWISP static website, built with Pelican and a custom frontend theme.
Core website inputs are organized as follows:
content/contains pages, blog posts, and other published content.theme/contains Pelican templates and theme resources.css/andjs/contain frontend source files.theme/static/andoutput/contain generated website assets and pages.pelicanconf.py,publishconf.py,Makefile, andpackage.jsondefine website builds and configuration.
- Use
README.rstandMakefilefor local setup, build, and serving commands. - Use
requirements.txt,package.json,yarn.lock, and.github/workflows/ci.ymlfor CI-tested dependencies and build behavior. - Use the relevant content, template, and configuration files to determine website behavior.
If instructions conflict, repository configuration and CI workflows win first, documentation next, and this file is supplemental.
- Before editing, inspect the relevant implementation, tests, documentation, and configuration. Follow existing repository patterns and do not invent behavior or requirements.
- Keep each contribution focused and change only the lines necessary for its goal. Do not include unrelated refactors, formatting churn, or generated and dependency-file changes unless explicitly required.
- Run
openwisp-qa-formatafter each change when available. - Run the relevant targeted tests, builds, and documented QA checks, including
./run-qa-checkswhen provided. Do not claim a change is complete when verification fails; report the failure or blocker. - When requirements, intended behavior, or an unexpected failure are unclear, stop and seek clarification instead of making speculative changes.
- When starting work on a new issue, create a new branch from
master. Useissues/<issue-number>-<short-title>for issue work; otherwise, use a short, descriptive branch name. - Commit messages must be descriptive and use past tense. Past tense is a writing guideline that agents and contributors must follow; it is not checked automatically. For issue work, use an allowed prefix and a capitalized, past-tense subject ending with
#<issue-number>, for example[fix] Fixed perennial "modified" state #213. Repeat the issue reference in the body withFixes,Closes,Resolves, orRelated toas appropriate. After creating a commit, useopenwisp-commit --checkto validate the currentHEAD; it cannot validate a proposed message. Useopenwisp-commit --check --rev-range <range>for an existing commit range, andcz -n cz_openwisp infoto view allowed prefixes and message structure. - Add an explanatory commit body only for substantial changes, new features, or non-obvious bug fixes. The releaser automatically publishes the subject of
[feature],[change],[change!],[deps], and[fix]commits, including scoped variants, in the changelog. Write those subjects in clear, user-friendly language suitable for release notes. - Send new commits in response to review feedback instead of amending existing commits.
- Follow the DRY principle: do not duplicate information or code across files.
- Treat
css/theme.scssas the source stylesheet for website CSS changes. - Do not edit generated
theme/static/css/,theme/static/js/, Font Awesometheme/static/webfonts/fa-*, oroutput/; edit their source inputs and rebuild them with the documented commands. - After changing
css/theme.scss, rebuild CSS withnpm run build:cssor run the full website build withmake html. - Keep generated and dependency directories out of source fixes unless explicitly requested.
- Update content, templates, configuration, and documentation together when website behavior, navigation, setup, or published information changes.
- Prefer short, precise names that rely on their nearest meaningful scope. Do not repeat a feature, domain object, or namespace already named by the containing module, class, or function. For example, prefer
EstimatedLocation.refresh()overEstimatedLocation.refreshEstimatedLocation(). Repeat that context only when the name is used outside that scope or is needed to distinguish genuinely different concepts. When a concise name cannot express a necessary distinction, use a concise docstring to describe it rather than encoding it in an excessively long name. - Before adding a comment or docstring, ask whether it conveys information a reader cannot reasonably infer from clear code, names, and surrounding scope. Add a concise comment when it explains a non-obvious reason, constraint, compatibility or security requirement, side effect, or unavoidable complexity. In opaque syntax or domain-specific code, especially shell scripts, a comment may also explain what the code does. Do not add comments that merely restate adjacent code one-to-one.
- For content-only or Pelican logic changes that do not affect frontend assets, run
make html SKIP_YARN=1while iterating. - Run
make htmlwhen CSS, JavaScript, frontend dependencies, or generated frontend assets need rebuilding. - Keep helpers and classes used by only one test method inside that method. Promote them to class or module scope only when genuinely reused.
- Preserve safe browser-facing behavior in templates and content: escape untrusted values, review embeds and generated assets, validate redirects, and use safe external links.
- Do not expose configuration secrets or credentials in content, templates, generated assets, or repository configuration.
- If documentation and CI commands differ, use CI for verification and report the exact documentation path, CI workflow path, and differing commands. Do not change the documentation until the user explicitly chooses one of these actions: update the named documentation file in the current change because the divergence was caused by that change, or leave it unchanged for a separate follow-up. Never decide that scope distinction independently.