Contributing Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• README.en.md
• SECURITY.md
• orca.yaml
• README.md

These guidelines define the processes and standards for participating in the OpenHWP project. As an open-source HWP/HWPX desktop application, OpenHWP relies on a specific Deno-based toolchain and a rigorous workflow to maintain code quality and community health. The project emphasizes clear communication through English documentation, commit messages, and a structured approval process for external contributions.

Contributors are expected to adhere to the Code of Conduct and follow technical workflows involving Deno tasks for linting, formatting, and testing. Because the project is in its early stages, contributions must be coordinated through issues or discussions before any code is submitted.

Sources: CONTRIBUTING.md:1-8, README.en.md:5-13

Technical Environment and Setup

OpenHWP utilizes a single Deno toolchain for development, execution, and packaging. It specifically requires Deno version 2.9.0 or higher to support deno desktop features. The project avoids multiple runtimes like Node.js, Bun, or Mise.

Prerequisites and Initialization

To begin development, clones of the repository must initialize dependencies using Deno. The project also supports automated worktree setup via the orca.yaml configuration.

git clone https://github.com/pleaseai/openhwp.git
cd openhwp
deno install

Sources: CONTRIBUTING.md:10-14, README.en.md:46-48, orca.yaml:14-17

Toolchain Commands

The following Deno tasks are required to maintain the project's baseline quality:

Task	Command	Description
Linting	deno lint	Checks for programmatic and stylistic errors.
Formatting	deno fmt --check	Validates code style against project standards.
Testing	deno test	Executes the test suite.
Development	deno task dev	Runs the application in development mode.

Sources: CONTRIBUTING.md:24-26, README.en.md:51-51

Development Workflow

The workflow is designed to ensure that every change is intentional and vetted. This begins with community discussion rather than immediate code submission.

Contribution Lifecycle

The following diagram illustrates the path from identifying a need to merging a pull request:

The project explicitly discourages "drive-by" AI-generated pull requests and requires maintainer approval before external PRs are kept open.

Sources: CONTRIBUTING.md:30-45, CONTRIBUTING.md:50-59

Branching and Commits

• Branching: Create focused branches from main using prefixes like feat/ or fix/.
• Commit Messages: Follow Conventional Commits. Formats must be type(scope): subject. Supported types include feat, fix, docs, refactor, test, and chore.
• Breaking Changes: Must include a BREAKING CHANGE: footer to facilitate automated versioning and changelog generation.

Sources: CONTRIBUTING.md:18-20, CONTRIBUTING.md:28-33

Security and Reporting

Security is handled outside of the standard public contribution flow to prevent premature disclosure of vulnerabilities.

Vulnerability Reporting Process

Security issues must be reported privately. Public issues, discussions, or PRs for vulnerabilities are prohibited.

Code of Conduct

All contributors must adhere to the Contributor Covenant. The project leaders enforce these standards to maintain a healthy community environment.

Standards of Behavior

• Positive Behavior: Demonstrating empathy, accepting constructive feedback, and focusing on the community's best interests.
• Unacceptable Behavior: Trolling, personal attacks, sexualized language, and public/private harassment.

Enforcement Ladder

Community leaders follow a tiered impact guideline for violations:

1. Correction: Private written warning and potential request for public apology.
2. Warning: Warning with consequences for continued behavior, including interaction restrictions.
3. Temporary Ban: A time-bound prohibition from community interaction.
4. Permanent Ban: Permanent removal from the community for patterns of violation or serious aggression.

Sources: CODE_OF_CONDUCT.md:8-32, CODE_OF_CONDUCT.md:65-103

Summary

Contributing to OpenHWP requires a "discussion-first" approach where maintainers guide the implementation of bugs and features. The project relies on the Deno 2.9+ ecosystem and enforces Conventional Commits to maintain a clean history and automated release cycle. By following these guidelines, contributors help build a robust, open-source HWP engine while maintaining a professional and inclusive environment.

Sources: CONTRIBUTING.md:1-5, README.en.md:11-15