Files

T

2026-03-17 18:41:07 -05:00

7.4 KiB

Raw Blame History

Contributing to MokoStandards-Template-Joomla-Module

Thank you for your interest in contributing to this project! This document provides guidelines and instructions for contributing.

Code of Conduct
Getting Started
Development Process
Coding Standards
Commit Guidelines
Pull Request Process
Reporting Issues
Questions and Support

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hello@mokoconsulting.tech.

Getting Started

Prerequisites

Before contributing, ensure you have:

PHP 7.4 or higher installed
Composer installed (for dependency management)
PHP CodeSniffer installed (composer global require squizlabs/php_codesniffer)
A working Joomla installation for testing
Git installed and configured

Setting Up Your Development Environment

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/your-username/MokoStandards-Template-Joomla-Module.git
cd MokoStandards-Template-Joomla-Module

Add the upstream remote:

git remote add upstream https://github.com/mokoconsulting-tech/MokoStandards-Template-Joomla-Module.git

Configure git commit template:
```
git config commit.template .gitmessage
```
Install development dependencies:
```
composer install
```

Development Process

Branching Strategy

main - Stable, production-ready code
feat/* - New features
fix/* - Bug fixes
docs/* - Documentation updates
refactor/* - Code refactoring
chore/* - Maintenance tasks

Workflow

Create a branch from main:

git checkout main
git pull upstream main
git checkout -b feat/your-feature-name

Make your changes following our coding standards

Test your changes:

make validate    # Run linters and code standards checks
make build       # Build the module package

Commit your changes using conventional commits (see below)
Push to your fork:
```
git push origin feat/your-feature-name
```
Open a Pull Request from your branch to main

Coding Standards

PHP Standards

Follow Joomla Coding Standards
Use tabs for indentation (width: 2 spaces)
Use UTF-8 encoding without BOM
Use LF (Unix) line endings
Include proper DocBlocks for classes, methods, and properties
Use type hints where applicable

File Headers

All PHP files should include the following header:

<?php
/**
 * @package     ModuleName
 * @subpackage  mod_modulename
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
 */

defined('_JEXEC') or die;

Code Quality

Before submitting:

Run PHP syntax check: make lint
Run PHP CodeSniffer: make phpcs
Run all checks: make validate
Fix auto-fixable issues: make phpcbf

Commit Guidelines

We follow Conventional Commits specification.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Code style changes (formatting, missing semicolons, etc.)
refactor: Code change that neither fixes a bug nor adds a feature
perf: Performance improvements
test: Adding or updating tests
build: Changes to build system or dependencies
ci: Changes to CI configuration
chore: Other changes that don't modify src or test files
revert: Reverts a previous commit

Examples

# Feature
feat(module): add contact form validation

# Bug fix
fix(display): correct responsive layout on mobile devices

# Documentation
docs(readme): update installation instructions

# Breaking change
feat(api)!: change module configuration structure

BREAKING CHANGE: Configuration now uses nested arrays instead of flat structure

Rules

Use imperative, present tense: "change" not "changed" nor "changes"
Don't capitalize first letter
No period (.) at the end
Keep subject line under 50 characters
Wrap body at 72 characters
Separate subject from body with a blank line
Use body to explain what and why vs. how

Pull Request Process

Before Submitting

Update documentation if you've changed functionality
Update CHANGELOG.md with a description of changes
Ensure all tests pass: make validate
Ensure no merge conflicts with main
Keep commits atomic - one logical change per commit
Squash commits if you have multiple small commits for one change

Pull Request Guidelines

Title: Use conventional commit format
Description: Explain what and why (not how)
Link issues: Use "Closes #123" or "Fixes #123"
Screenshots: Include for UI changes
Breaking changes: Clearly document any breaking changes
Documentation: Include relevant documentation updates

Review Process

At least one maintainer must review and approve
All CI checks must pass
No unresolved review comments
Branch must be up to date with main

After Merge

Delete your feature branch
Pull the latest main branch
Update your fork

Reporting Issues

Bug Reports

When reporting bugs, include:

Clear title: Brief description of the issue
Environment: PHP version, Joomla version, OS
Steps to reproduce: Numbered list of steps
Expected behavior: What should happen
Actual behavior: What actually happens
Screenshots: If applicable
Error messages: Full error text or stack traces

Feature Requests

When requesting features, include:

Clear title: Brief description of the feature
Problem statement: What problem does this solve?
Proposed solution: How should it work?
Alternatives considered: Other approaches you've thought about
Additional context: Any other relevant information

Issue Labels

bug - Something isn't working
enhancement - New feature or request
documentation - Improvements or additions to documentation
good first issue - Good for newcomers
help wanted - Extra attention is needed
question - Further information is requested

Questions and Support

Documentation: Check the docs/ directory first
Issues: Search existing issues before creating new ones
Email: hello@mokoconsulting.tech
Discussions: Use GitHub Discussions for general questions

Development Resources

License

By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0 or later.

Thank you for contributing to MokoStandards-Template-Joomla-Module!

7.4 KiB Raw Blame History