diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09eba7b..ea9a5fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,245 +1,141 @@ - -# Contributing +1. **Create a feature branch** from `dev`: + ```bash + git checkout dev && git pull + git checkout -b feature/my-change + ``` -Thank you for your interest in contributing. This document defines the baseline expectations, workflows, and quality gates for any change entering this repository. +2. **Work and commit** on your feature branch. Push to origin. -The objective is to keep contributions predictable, reviewable, and compliant with MokoStandards while enabling a sustainable delivery pipeline. +3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it. -## Governance and scope +4. **When ready for release**, open a **draft PR**: `dev` → `main`. + - This automatically renames the source branch to `rc` (release candidate) + - An RC pre-release is built and uploaded -This CONTRIBUTING file operates alongside the following governance assets: +5. **Alpha and beta branches** are created by manually renaming the branch before the RC stage: + - Rename `dev` to `alpha` for early testing → alpha pre-release is built + - Rename `alpha` to `beta` for feature-complete testing → beta pre-release is built + - When the draft PR is created, the branch is renamed to `rc` -* `README.md` for project overview and onboarding -* `LICENSE` for legal terms and reuse constraints -* `CODE_OF_CONDUCT.md` for behavioral expectations +6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`. -In case of conflict, legal terms in `LICENSE` take precedence, followed by this document. +7. **Merging to main** triggers the stable release pipeline: + - Minor version bump (e.g., `02.09.xx` → `02.10.00`) + - Stability suffix stripped (clean version) + - Gitea release created with ZIP/tar.gz packages + - `updates.xml` updated (Joomla extensions) + - `dev` branch recreated from `main` -## Alignment with MokoStandards +### Branch summary -All Moko Consulting projects are expected to comply with the shared standards defined in the `MokoStandards` repository. +| Branch | Purpose | Created by | +|--------|---------|-----------| +| `feature/*` | New features and fixes | Developer | +| `dev` | Integration branch | Auto-recreated after release | +| `alpha` | Alpha pre-release testing | Manual rename from `dev` | +| `beta` | Beta pre-release testing | Manual rename from `alpha` | +| `rc` | Release candidate | Auto-renamed on draft PR to main | +| `main` | Stable releases | Protected, merge only | +| `version/XX.YY.ZZ` | Archived release snapshots | Auto-created by CI | -* Source of truth: [https://github.com/mokoconsulting-tech/MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) -* Areas covered: headers, licensing, coding style, documentation layout, and CI expectations +### Protected branches -Per project policy, this file should reference standards rather than redefining them. Any deviation must be explicitly documented. +| Branch | Direct push | Merge via | +|--------|------------|-----------| +| `main` | Blocked (CI bot whitelisted) | PR merge only | +| `dev` | Blocked (CI bot whitelisted) | PR merge from feature/* | +| `rc` | Blocked (CI bot whitelisted) | Auto-created on draft PR | +| `alpha` | Blocked (CI bot whitelisted) | Manual rename | +| `beta` | Blocked (CI bot whitelisted) | Manual rename | +| `feature/*` | Open | N/A (source branch) | -## Ways to contribute +## Version Policy -Contributions are welcome across multiple workstreams: +### Format -* Bug reports and defect reproduction scenarios -* Feature requests aligned with the project roadmap -* Code changes, including refactors and technical debt reduction -* Documentation improvements and clarifications -* Test coverage (unit, integration, and regression scenarios) +All versions use `XX.YY.ZZ` — three two-digit segments, zero-padded: -Before investing significant effort, contributors are encouraged to review the open issues and roadmap documents to avoid misalignment. +- **XX** — Major version (breaking changes) +- **YY** — Minor version (new features, bumped on release to main) +- **ZZ** — Patch version (auto-incremented on every push to dev/feature branches) -## Communication channels +Rollover: patch `99` → `00` increments minor; minor `99` → `00` increments major. -Typical communication paths include: +### Stability suffixes -* GitHub Issues for bug reports, feature requests, and questions -* GitHub Discussions for design conversations, Q&A, and community engagement -* Pull Requests for change proposals +Each branch appends a suffix to indicate stability: -## Issue workflow +| Branch | Suffix | Example | +|--------|--------|---------| +| `main` | (none) | `02.09.00` | +| `dev` | `-dev` | `02.09.01-dev` | +| `feature/*` | `-dev` | `02.09.01-dev` | +| `alpha` | `-alpha` | `02.09.01-alpha` | +| `beta` | `-beta` | `02.09.01-beta` | +| `rc` | `-rc` | `02.09.01-rc` | -Use GitHub Issues as the system of record for all work. +### Auto version bump -When opening an issue: +On every push to `dev`, `alpha`, `beta`, `rc`, or `feature/*`: -1. Search existing issues to avoid duplication. -2. Select the appropriate issue template if available. -3. Provide a concise, action oriented title. -4. Supply a clear description including: +1. Patch version incremented +2. Stability suffix applied based on branch name +3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.) +4. Commit created with `[skip ci]` to avoid loops - * Expected behavior - * Actual behavior - * Minimal steps to reproduce - * Environment details (version, platform, configuration) -5. Attach logs, screenshots, or configuration snippets as needed, after removing sensitive data. +### Version files -Maintainers will triage issues based on impact, risk, and alignment with the roadmap. Not all requests will be accepted, but all will be reviewed in good faith. +The version tools update all files containing version stamps: -## Pull request workflow +- `.mokogitea/manifest.xml` (canonical source) +- Joomla XML manifests (`` tag) +- `README.md`, `CHANGELOG.md` (`VERSION:` pattern) +- `package.json`, `pyproject.toml` +- Any text file with a `VERSION: XX.YY.ZZ` label -Pull Requests (PRs) are the primary integration path for changes. +Files synced from other repos (with a `# REPO:` header) are not touched. -Standard workflow: +## Code Standards -1. Open or reference an issue describing the problem or enhancement. -2. Fork the repository or create a feature branch from the canonical default branch (commonly `main` or `master`). -3. Implement changes aligned with the coding standards and file header requirements. -4. Add or update tests to validate the behavior. -5. Update documentation where behavior, configuration, or interfaces change. -6. Run the full test and linting suite locally before opening the PR. -7. Open a PR with: +- **PHP**: PSR-12, tabs for indentation +- **Copyright**: all files must include the Moko Consulting copyright header +- **License**: SPDX identifier `GPL-3.0-or-later` (or as specified per repo) +- **Attribution**: use `Authored-by: Moko Consulting` in commits, not individual names - * A precise, descriptive title - * A summary of changes - * Explicit linkage to the corresponding issue - * Notes on testing performed and any known limitations +## Commit Messages -PRs must pass automated checks before they will be considered for review. The maintainer team reserves the right to request revisions, split changes, or defer work that does not align with the current release plan. +Use conventional commit format: -## Merge strategy +``` +type(scope): short description -This repository uses **squash merge** as the only permitted merge method for pull requests to the main branch. This ensures a clean, linear git history where each commit represents a complete, reviewed change. +Optional body with context. -Key implications for contributors: +Authored-by: Moko Consulting +``` -* **PR Title is Important**: The PR title becomes the commit message subject. Make it clear and descriptive. -* **PR Description is Important**: The PR description becomes the commit message body. Include rationale and summary of changes. -* **Automatic Cleanup**: Branches are automatically deleted after merge. -* **No Merge Commits**: Regular merge commits and rebase merges are disabled. +Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `ci` -## Branching and versioning +Special flags in commit messages: +- `[skip ci]` — skip all CI workflows +- `[skip bump]` — skip auto version bump only -Unless specified otherwise: +## Reporting Issues -* Default development branch: `main` -* Feature work: short lived feature branches named using a predictable convention, for example `feature/` or `fix/` -* Releases: tagged using semantic versioning (`MAJOR.MINOR.PATCH`) - -## Coding standards and file headers - -This project adheres to the coding conventions and header rules defined in MokoStandards. At a minimum: - -* All source and configuration files must include the standard SPDX compatible header where applicable. -* Language specific style guides (for example PHP, JavaScript, Python) must be followed. -* Follow Joomla coding standards for PHP code. - -## Commit message guidelines - -Commit messages are part of the project audit trail. They should be structured and descriptive. - -Recommended format: - -* Short subject line in the imperative mood, for example `Add`, `Fix`, `Refactor` -* Optional body that explains the rationale, constraints, and side effects -* Reference to related issues using `Fixes #` or `Refs #` as appropriate - -Avoid bundling unrelated changes into a single commit. Small, logically grouped commits improve traceability and rollback options. - -## Testing expectations - -Before opening a PR, contributors are expected to: - -* Run all available automated tests (unit, integration, and other configured checks) -* Ensure linting and static analysis pass without new violations -* Test changes with a local Joomla installation when applicable - -For new features or non trivial fixes, please include tests that: - -* Reproduce the defect, or -* Demonstrate the new behavior - -If tests are not included, the PR should clearly state why (for example, infrastructure limitations, complex external dependencies, or pure documentation changes). - -## Documentation contributions - -Documentation is a first class asset in this ecosystem. - -When contributing documentation: - -* Align with the established docs hierarchy (for example `docs/`) -* Apply the shared template structure for new documents -* Include appropriate navigation, metadata, and revision history sections when required by the documentation standards - -Minor corrections such as typo fixes are welcome, but larger structural changes should be coordinated via an issue or design note first. - -## Security and responsible disclosure - -Security sensitive issues must not be reported in public issues. - -Use the security contact channel defined in `SECURITY.md` to share details. - -Provide enough information for maintainers to reproduce and understand the impact. The team will coordinate fixes and disclosure timelines as appropriate. - -## License and contributor agreement - -Unless stated otherwise, contributions to this repository are accepted under the same license as the project, GPL 3.0 or later. - -By submitting a contribution, you confirm that: - -* You have the right to contribute the code or content. -* You agree that your contribution will be licensed under the project license. -* You will not submit content that infringes third party rights. - -## Escalation and decision making - -If you disagree with a review decision or prioritization decision: - -1. Escalate by commenting on the issue or PR with your reasoning. -2. Request a second review from a different maintainer. -3. Contact the project maintainers directly via the channels listed in README.md. - -Final decisions rest with the project maintainers, but all concerns will be considered fairly. +Use the repository's issue tracker with the appropriate template. --- -## Contact - -For questions or clarifications about this contributing guide: - -* Open a GitHub Issue -* Contact: hello@mokoconsulting.tech - -Thank you for contributing to this project and supporting the MokoStandards ecosystem! - -## Infrastructure Standards - -All repositories in the MokoConsulting org follow these conventions: - -### Release Tags - -Every repo maintains 5 standard release channel tags: - -- `development` - Active development builds -- `alpha` - Early internal testing -- `beta` - Broader testing / client UAT -- `release-candidate` - Final QA before production -- `stable` - Production release - -### Branch Protection - -- `main` is protected; only `jmiller` can push directly -- All other contributors must use pull requests -- PRs are automatically reviewed by Claude Code - -### CI/CD - -- Gitea Actions runs all CI workflows -- GitHub Actions are disabled on mirrored repos -- Workflows live in both `.github/workflows/` and `.gitea/workflows/` - -### Update Servers (Joomla) - -In manifest ``, Gitea must be priority 1, GitHub priority 2. - -### Secrets - -All repos have `GA_TOKEN` and `GH_TOKEN` as Actions secrets for API access. +*Moko Consulting *