🤝 Contributing to PhPstrap

Thanks for helping improve PhPstrap! This guide explains how to report issues, propose features, submit pull requests, write modules, and improve docs.

1) Project Values

• Simple first: Prefer clear, minimal solutions over clever complexity.
• Stable surface: Don’t break public APIs without discussion and a migration path.
• Security & privacy: Safe defaults; no secrets in repos; least privilege.
• Accessibility: Semantic HTML, keyboard navigation, and WCAG-minded styles.

2) Ways to Help

• 🪲 Report bugs with a minimal reproduction.
• ✨ Request features with a clear use case and alternatives considered.
• 🧩 Build modules (e.g., SMTP, hCapture) and publish them.
• 📝 Improve docs (guides, examples, screenshots).
• 🧪 Add tests or improve coverage for fragile code paths.

3) Issues: Bugs & Feature Requests

Open an issue on GitHub with:

• Environment: PHP version, web server, database.
• Steps to reproduce: Smallest possible example.
• Expected vs actual behavior and relevant logs (omit secrets).

4) Local Dev Setup

1. Fork the repo on GitHub and clone your fork.

git clone https://github.com/<you>/phpstrap.git
cd phpstrap

2. (Optional) Install dev tools via Composer if the repo provides them.

composer install

3. Create DB and copy config, then edit credentials.

cp includes/config.sample.php includes/config.php
# update DB_*, BASE_URL, etc.

4. Run installer at http://localhost:8000/install.php (or your vhost).
5. Serve locally:

php -S localhost:8000 -t .

5) Coding Standards

• PHP: PHP 8+, PSR-12 style. Prefer strict types where practical.
• Security: Escape output, parameterize queries, verify CSRF tokens, validate inputs.
• CSS: Bootstrap 5 utilities first; custom rules in /css/custom.css.
• JS: Small, framework-free snippets; progressive enhancement.

Formatting tools (if present):

# Examples (only if configured in the repo)
composer phpcs
composer phpstan
composer fix

6) Git Workflow

1. Fork → feature branch → PR to main.
2. Keep PRs focused and small; one topic per PR.
3. Use Conventional Commits for messages: feat: add admin cache clear tool, fix: sanitize module title.
4. Rebase onto latest main before opening/updating PRs.

7) Pull Request Checklist

• [ ] Clear title & description (what/why, screenshots if UI).
• [ ] Backward compatible (or includes a migration + notes).
• [ ] Tests updated/added if logic changed.
• [ ] Docs updated (this site or module README).
• [ ] No secrets, keys, or personal data in code or commit history.

8) Module Contributions

Modules live under /modules/<name> or as separate repos. Minimum scaffold:

modules/
  my-module/
    module.php
    routes.php
    migrations/
    views/
    assets/
    README.md

Recommended modules.json entry:

[
  {
    "name": "my-module",
    "title": "My Module",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "What it does",
    "url": "https://github.com/YourOrg/my-module",
    "requires_php": ">=8.0",
    "requires_phpstrap": ">=1.0.0"
  }
]

9) Documentation Changes

• Docs live in /docs/ (Jekyll-compatible). Use the existing frontmatter format.
• Keep language concise; prefer runnable examples over long prose.
• Include version notes if behavior differs by release.

10) Testing

• Write unit tests for pure logic; smoke test pages in a browser.
• Validate forms (server + client) and confirm CSRF on state changes.
• Test both light/dark themes and mobile breakpoints.

11) Security Policy

• Report privately via GitHub Security Advisories (or the repo’s SECURITY.md if present).
• Include affected versions, PoC, and impact assessment.
• We coordinate disclosure and patch releases; credit is given after fixes ship.

12) Releases & Versioning

• SemVer: MAJOR.MINOR.PATCH (breaking / features / fixes).
• Changelogs summarize noteworthy changes, migrations, and security notes.
• Tag releases in Git; publish release notes with upgrade steps.

13) License

By contributing, you agree that your contributions will be licensed under the project’s license (see License).

14) Community

• GitHub Issues: bug reports & features.
• GitHub Discussions (if enabled): Q&A, ideas, design proposals.
• PR reviews: be respectful, discuss trade-offs, and prefer evidence over opinion.

Thanks for helping make PhPstrap better. We ❤️ your contributions!