Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
243 lines (175 loc) · 8.19 KB

CONTRIBUTING.md

File metadata and controls

243 lines (175 loc) · 8.19 KB
Raw

Contributing to Proclaim

Thank you for your interest in contributing to Proclaim! This document provides guidelines for contributing to the project.

Project Overview

Proclaim (CWM Proclaim) is a Joomla 5+ component for managing and displaying Bible studies and sermons. It supports teachers, series, topics, locations, media files, podcasting, and social sharing with customizable templates.

  • Minimum PHP: 8.3+
  • Minimum Joomla: 5+ (must work on Joomla 6 without backward compatibility layer)
  • Namespace: CWM\Component\Proclaim
  • License: GPL-2.0-or-later

Getting Started

Development Setup

  1. Fork and clone the repository
  2. Install dependencies: 
    composer install --dev
npm install
  3. Set up your development environment: 
    composer setup
composer symlink

Branch Strategy

  • Main branch: development (all PRs target this branch)
  • Feature branches: feature-descriptive-name
  • Bug fixes: fix-descriptive-name

Code Standards

PSR-12 Coding Standard

This project follows PSR-12 coding standards, enforced by PHP CS Fixer.

Before committing, always run:

composer lint:fix

Key requirements:

  • 4-space indentation (no tabs)
  • Line length should not exceed 120 characters
  • Space after type casts: (int) $var, (string) $value
  • Opening brace on same line for control structures
  • One blank line after namespace and use statements

Joomla 5+ API Requirements

Use modern Joomla APIs only:

  • ✅ getDatabase() / ❌ getDbo() or $this->_db
  • ✅ getIdentity() / ❌ getSession()->get('user')
  • ✅ Exceptions / ❌ getError()/setError()
  • ✅ MVCFactory createModel()/createTable() / ❌ new ClassName()
  • ✅ $this->input in controllers / ❌ new Input()
  • ❌ No deprecated APIs: jimport(), getErrorMsg(), CMSObject, etc.

Code must work WITHOUT Joomla's backward compatibility plugin enabled.

Naming Conventions

  • Class names use Cwm prefix: CwmteacherTable, CwmparamsModel
  • Follow Joomla's MVC naming conventions
  • Use descriptive variable and method names

Testing

Running Tests

# Run PHP tests
composer test

# Run JavaScript tests
npm test

# Run all checks (linting + tests)
composer check:all

Test Requirements

  • PHP: PHPUnit tests in tests/unit/
  • JavaScript: Jest tests in tests/js/
  • All tests must pass before PR approval
  • Add tests for new features and bug fixes

Code Coverage

Aim for meaningful test coverage, especially for:

  • New features
  • Bug fixes
  • Complex business logic
  • Helper functions

Pull Request Process

  1. Create a feature/fix branch from development
  2. Make your changes following code standards
  3. Run tests and linting: 
    composer lint:fix
composer check:all
  4. Commit with clear messages:
    • Use descriptive commit messages
    • Reference issue numbers when applicable
  5. Push and create PR targeting development
  6. PR Description should include:
    • Clear description of changes
    • Reference to related issues/discussions
    • Testing performed
    • Screenshots (for UI changes)

PR Review

  • All PRs require review before merging
  • Address review feedback promptly
  • Maintain a respectful, collaborative tone
  • CI checks must pass

Documentation

  • Code documentation: Use PHPDoc blocks for classes and methods
  • Project documentation: Lives in the Proclaim.wiki repository
  • Update wiki documentation for new features
  • Release notes go in wiki as Whats-New-X.X.md

Issue Tracking

  • Bug reports: Use GitHub Issues
  • Feature requests: Use GitHub Discussions
  • Security issues: See SECURITY.md

Reporting Bugs

Include:

  • Proclaim version
  • Joomla version
  • PHP version
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages/logs

Issue Hygiene

  • Triage on read: if you open an issue that's missing a label (type: *, priority: *, area: *, status: *), a milestone, or template fields (repro steps, version info), fill in what you can before moving on — don't leave it for someone else to re-derive later.
  • Labels are namespaced. There is no bare bug or enhancement label — use type: bug, type: feature, type: enhancement, type: docs, type: refactor, type: chore, type: security or type: test. gh fails the whole command and creates nothing when given a label that does not exist, so run gh label list rather than guessing.
  • Set the issue Type: Task, Bug, or Feature. This is a separate field from the labels, not a duplicate of them — gh issue edit <n> --type Feature. Types apply to issues only; a PR can't carry one.
  • Put it on the board: issues belong to the Proclaim Development project, with Status set to where the work actually is — Triage → Backlog → In Progress → In Review → Done.
  • Fill in the sidebar fields where you know them: Priority, Effort, and the Start date / Target date pair. Priority mirrors the priority: * label rather than replacing it — set both.
  • Multi-issue features: apply the epic label and use an epic/{N}-{slug} integration branch, with sub-PRs targeting that branch instead of development.
  • Link branches to their issue: don't just name a branch after the issue number — run gh issue develop <issue-number> --branch <name> (or use the issue's "Create a branch" button) so the branch and its PR show up under the issue's Development section automatically.

Issue #1857 is a worked example of all of the above.

PR Hygiene

PRs need the same metadata as issues — a linked branch alone isn't enough:

  • Mirror the linked issue's labels (type: *, priority: *, area: *) onto the PR. Docs-only or other PRs with no linked issue just skip labels. The issue Type field is not mirrored — a PR cannot carry one.
  • Assign the PR (and its linked issue, if not already) to whoever is doing the work.
  • Milestone: use the milestone matching active_development in build/versions.json (e.g. 10.5.10) for patch/bugfix work; create it if it doesn't exist yet. Larger breaking work goes in the next major milestone (e.g. v11.0.0) instead.
  • A milestone is the release the work ships in — nothing else. Accepted work with no target release is Status: Backlog on the project board, not a Backlog milestone. The old Backlog milestone is closed; don't reopen the habit by copying the milestone off whatever PR merged last.

Versioning

Check build/versions.json for version numbers:

  • Use next.minor for @since tags (currently 10.1.0)
  • Use next.major for breaking changes (currently 11.0.0)

Building

# Install dependencies
composer install --dev
npm install

# Build frontend assets
composer build:assets

# Build component package
composer build

# Full build with all checks
composer build:full

Common Tasks

# Check PHP syntax
composer lint:syntax

# Check code style
composer lint

# Fix code style
composer lint:fix

# Run specific test file
./libraries/vendor/bin/phpunit tests/unit/Admin/Helper/CwmparamsTest.php

# Sync language files
composer sync-languages

# Bump version
composer version -- -v 10.2.0

Platform Targets

  • Code must work natively on Joomla 5 and 6
  • Avoid ALL deprecated Joomla APIs
  • Test without backward compatibility layer
  • PHP 8.3+ required (use modern PHP features)

Getting Help

Code of Conduct

  • Be respectful and professional
  • Welcome newcomers and help them learn
  • Focus on constructive feedback
  • Respect different perspectives and experience levels

License

By contributing to Proclaim, you agree that your contributions will be licensed under the GPL-2.0-or-later license.

Thank you for contributing to Proclaim! Your efforts help make this project better for the entire community.