Contributing Workflow

Contributing Workflow

This document explains how we use GitHub to track bugs, features, and development work on Proclaim. For coding standards and conventions, see Standards and Conventions.

Overview

Idea / Bug Report
       |
       v
  Discussion (Ideas / Q&A)
       |
       v  (accepted)
  Issue (with Type + Labels + Milestone)
       |
       v  (added to board)
  Project Board: Triage -> Backlog -> In Progress -> In Review -> Done
       |
       v
  Pull Request -> Merge -> Done

Discussions

Use GitHub Discussions for ideas and questions that haven't been committed to yet.

Category	Purpose
Ideas	Feature proposals -- discuss, refine, vote before committing to build
Q&A	User support questions -- mark as answered when resolved
General	Announcements, release updates, roadmap
Show and tell	Churches sharing how they use Proclaim
Polls	Community votes on direction

When an idea is accepted for development, use GitHub's "Create issue from discussion" button in the sidebar. This creates a linked issue and keeps the conversation history.

Issues

Issues represent committed work -- things we've agreed to do.

Issue Types

Every issue should have a Type set in the sidebar:

Type	Use for
Bug	Something is broken -- unexpected problem or behavior
Feature	New capability, idea, or functionality
Task	Internal work -- refactors, documentation, cleanup

Labels

Labels provide additional classification. Apply one from each relevant group:

Priority (how urgent):

Label	When to use
priority: critical	Blocks a release or breaks production
priority: high	Important, fix soon
priority: medium	Normal priority
priority: low	Nice to have, do when convenient

Area (where in the codebase):

Label	Scope
area: admin	Admin backend
area: site	Frontend
area: modules	Modules
area: api	REST API

Status (only for special states):

Label	When to use
status: awaiting-feedback	Waiting on the reporter or a contributor to respond
status: blocked	Cannot proceed -- dependency on another issue or external factor

Utility (applied as needed):

duplicate, wontfix, question, Help Wanted, dependencies, php, javascript

Creating a Good Issue

For bugs:

• Set Type to Bug
• Add a priority label and area label
• Include steps to reproduce
• Include Proclaim version, Joomla version, PHP version
• Include error messages or screenshots if applicable

For features:

• Set Type to Feature
• Add a priority label and area label
• Link back to the Discussion where it was proposed (if applicable)
• Describe the desired behavior and why it's needed

For epics (large multi-phase work):

• Create a parent issue with a checklist of phases
• Use GitHub sub-issues to link individual phase issues
• The project board shows sub-issue progress automatically

Milestones

Every issue should be assigned to a milestone when the target release is known:

Milestone	What goes in it
v10.3.0	Issues planned for the next minor release
v11.0.0	Breaking changes saved for the next major release
Backlog	Accepted work with no target release yet

Milestones show a progress bar of open vs closed issues, which helps track release readiness.

Project Board

The Proclaim Development board provides a visual overview of all active work.

Columns

Column	Meaning
Triage	New issues land here automatically -- needs review
Backlog	Accepted and prioritized, not yet started
In Progress	Someone is actively working on it
In Review	Pull request is open, awaiting review
Done	Merged and complete

Automations

The board has these automations enabled:

• New items automatically go to Triage
• When an issue is closed, it moves to Done
• When a PR is merged, it moves to Done
• When a PR is linked to an issue, it moves to In Review
• Sub-issues are automatically added to the project

Pull Requests

Branch Naming

Type	Branch from	Example
Bug fix	main	fix/youtube-quota-limit
Feature	development	feature/landing-page-styles
Refactor	development	refactor/controller-traits

Before Submitting

1. Run composer lint:fix to fix code style
2. Run composer check:all to run all lints and tests
3. Reference the issue number in the PR description (e.g., "Closes #1156")

Review Process

1. PR is opened -- board auto-moves linked issue to In Review
2. Reviewer checks code, tests, and style
3. PR is merged -- board auto-moves to Done, linked issue auto-closes

Quick Reference

Reporting a bug: Open a Discussion in Q&A or create an Issue directly with Type: Bug

Proposing a feature: Post in Discussions > Ideas first, then convert to Issue when accepted

Starting work: Move your issue to In Progress on the board, create a branch, and go

Finishing work: Open a PR linked to the issue, get it reviewed and merged