<!--
 Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>

 This file is part of a Moko Consulting project.

 SPDX-License-Identifier: GPL-3.0-or-later

 # FILE INFORMATION
 DEFGROUP: Joomla.Template
 INGROUP: MokoOnyx.Governance
 REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
 FILE: CONTRIBUTING.md
 VERSION: 03.09.03
 BRIEF: Contribution guidelines for the MokoOnyx project.
 PATH: /CONTRIBUTING.md
 NOTE: This document defines contribution workflow, standards, and governance alignment.
-->

## Contributing

This document defines how to contribute to the MokoOnyx project. The goal is to ensure changes are reviewable, auditable, and aligned with project governance and release processes.

## Scope

These guidelines apply to all contributions, including:

* Source code changes
* Documentation updates
* Bug reports and enhancement proposals

## Prerequisites

Contributors are expected to:

* Have a working understanding of Joomla template structure.
* Be familiar with Git and GitHub pull request workflows.
* Review repository governance documents prior to submitting changes.
* Set up the development environment using the provided tools.

### Quick Setup

For first-time contributors:

```bash
# Clone the repository
git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git
cd MokoOnyx
```

See [docs/QUICK_START.md](./docs/QUICK_START.md) for detailed setup instructions.

## Development Tools

The repository provides several tools to streamline development:

* **Pre-commit Hooks**: Automatic local validation before commits

## Contribution Workflow

1. Fork the repository.
2. Create a branch from the active development branch.
3. Make focused, minimal changes that address a single concern.
4. Submit a pull request with a clear description of intent and impact.

Direct commits to protected branches are not permitted.

## Branching and Versioning

* Development work occurs on designated development branches.
* Releases are produced from versioned branches following repository standards.
* Contributors should not bump version numbers unless explicitly requested.

## Coding and Formatting Standards

All contributions must:

* Follow Joomla coding standards where applicable.
* Conform to Moko Consulting repository standards for headers, metadata, and file structure.
* Avoid introducing tabs, inconsistent path separators, or non portable assumptions.

Automated checks may reject changes that do not meet these requirements.

## Documentation Standards

Documentation changes must:

* Include required metadata and revision history sections.
* Avoid embedding version numbers in revision history tables.
* Preserve existing structure unless a structural change is explicitly proposed.

## Commit Messages

Commit messages should:

* Be concise and descriptive.
* Focus on what changed and why.
* Avoid referencing internal issue trackers unless required.

## Reporting Issues

Bug reports and enhancement requests should be filed as GitHub issues and include:

* Clear reproduction steps or use cases.
* Expected versus actual behavior.
* Relevant environment details.

Security related issues must follow the process defined in SECURITY.md and must not be reported publicly.

## Review Process

All pull requests are subject to review. Review criteria include:

* Technical correctness
* Alignment with project goals
* Maintainability and clarity
* Risk introduced to release and update processes

Maintainers may request changes prior to approval.

## License

By contributing, you agree that your contributions will be licensed under GPL-3.0-or-later, consistent with the rest of the project.

## Code of Conduct

Participation in this project is governed by the Code of Conduct. Unacceptable behavior may result in contribution restrictions.

---

## Metadata

* **Document:** CONTRIBUTING.md
* **Repository:** [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
* **Path:** /CONTRIBUTING.md
* **Owner:** Moko Consulting
* **Version:** 03.06.00
* **Status:** Active
* **Effective Date:** 2025-12-18
* **Last Reviewed:** 2025-12-18

## Revision History

| Date       | Change Summary                                                            | Author          |
| ---------- | ------------------------------------------------------------------------- | --------------- |
| 2025-12-18 | Initial publication of contribution guidelines and workflow expectations. | Moko Consulting |