Add templates documentation and update README

- Created comprehensive TEMPLATES.md guide - Documents all 5 issue templates and PR template - Includes MetaBuilder-specific guidelines - Covers data-driven architecture requirements - Details multi-tenancy considerations - Explains permission system (Levels 1-6) - Package system conventions - DBAL contribution guidelines - Updated README Contributing section - Added links to template documentation - Listed all available issue templates Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
2026-04-24 13:54:57 +00:00 · 2025-12-27 03:36:51 +00:00
parent 52daeccc37
commit 75e4cea3cd
2 changed files with 365 additions and 5 deletions
--- a/.github/TEMPLATES.md
+++ b/.github/TEMPLATES.md
@@ -0,0 +1,343 @@
+# Issue and Pull Request Templates
+
+This document describes the issue and PR templates available for MetaBuilder and how to use them effectively.
+
+## Overview
+
+MetaBuilder uses structured templates to ensure consistent, high-quality issues and pull requests. These templates are specifically designed for MetaBuilder's data-driven, multi-tenant architecture.
+
+## Issue Templates
+
+### Available Templates
+
+#### 🐛 Bug Report (`bug_report.yml`)
+Use this template to report bugs or unexpected behavior.
+
+**Key Features:**
+- Environment details capture (OS, Node version, browser, database)
+- Severity levels (Critical, High, Medium, Low)
+- Component categorization
+- Reproducible steps
+- Pre-submission checklist
+
+**Best For:**
+- Application crashes or errors
+- Features not working as expected
+- Performance issues
+- UI/UX bugs
+
+#### ✨ Feature Request (`feature_request.yml`)
+Request new features or enhancements aligned with MetaBuilder's architecture.
+
+**Key Features:**
+- Problem statement and solution proposal
+- Target user permission levels (Level 1-6)
+- Priority assessment
+- Use case descriptions
+- Technical considerations
+- Contribution willingness
+
+**Best For:**
+- New feature ideas
+- Improvements to existing features
+- API enhancements
+- User experience improvements
+
+#### 📚 Documentation (`documentation.yml`)
+Report documentation issues or request improvements.
+
+**Key Features:**
+- Documentation type categorization
+- Location/path specification
+- Suggested improvements
+- Documentation area targeting
+
+**Best For:**
+- Missing documentation
+- Outdated information
+- Unclear explanations
+- Broken links or typos
+- Missing code examples
+
+#### 📦 Package Request (`package_request.yml`)
+Request new packages for MetaBuilder's package system.
+
+**Key Features:**
+- Package naming (snake_case convention)
+- Package type selection
+- Minimum permission level
+- Component and Lua script planning
+- Database schema requirements
+- Multi-tenant consideration
+
+**Best For:**
+- New package ideas
+- Package integrations
+- Package improvements
+- Community packages
+
+**Special Considerations:**
+- Package names must use snake_case
+- Must specify multi-tenant requirements
+- Should include Lua script needs (MetaBuilder is 95% JSON/Lua)
+- Must declare dependencies
+
+#### 🔧 DBAL Issue (`dbal_issue.yml`)
+Report issues with the Database Abstraction Layer.
+
+**Key Features:**
+- Implementation selection (TypeScript/C++)
+- Operation type categorization
+- Conformance test status
+- Implementation parity checks
+- Severity levels
+
+**Best For:**
+- DBAL TypeScript SDK issues (`dbal/ts/`)
+- DBAL C++ daemon issues (`dbal/cpp/`)
+- YAML contract problems (`api/schema/`)
+- Conformance test failures
+- Implementation inconsistencies
+
+**Special Considerations:**
+- Check YAML schema definitions first
+- Run conformance tests if applicable
+- Verify tenant isolation
+- Note if both implementations behave differently
+
+### Template Configuration (`config.yml`)
+
+The config file provides:
+- Documentation links
+- Community discussion links
+- Private security reporting
+- Disables blank issues to ensure structure
+
+## Pull Request Template
+
+### Structure
+
+The PR template (`PULL_REQUEST_TEMPLATE.md`) includes comprehensive sections:
+
+#### 1. Basic Information
+- Description of changes
+- Related issue linking
+- Type of change
+- Component/area affected
+
+#### 2. Changes Made
+- Detailed list of code changes
+- Database/schema changes
+- Configuration changes
+
+#### 3. Testing
+- Test coverage (unit, integration, E2E)
+- Manual testing verification
+- Permission level testing
+- Multi-tenant scenario testing
+
+#### 4. Architecture & Design Decisions
+
+**Data-Driven Approach:**
+- Verify JSON/Lua architecture alignment
+- Use of declarative components
+- DBAL usage for database operations
+
+**Multi-Tenancy:**
+- TenantId filtering verification
+- Tenant isolation checks
+
+**Permission System:**
+- Permission checks at correct levels
+- AuthGate/canAccessLevel usage
+
+**Package System:**
+- Metadata structure compliance
+- Naming conventions (snake_case, semver)
+- Dependency declarations
+
+**Security:**
+- Input validation
+- XSS/SQL injection checks
+- Password hashing (SHA-512)
+- Lua sandbox restrictions
+- No secrets in code
+
+#### 5. Breaking Changes
+- Migration steps
+- Impact assessment
+- Upgrade guide
+
+#### 6. Documentation
+- README updates
+- API documentation
+- Architecture docs
+- Migration guides
+
+#### 7. Pre-Submission Checklist
+
+**Code Quality:**
+- Follows conventions (one lambda per file)
+- Uses MUI (not Radix/Tailwind)
+- ESLint passes
+- TypeScript compiles
+
+**Testing:**
+- All tests pass
+- Test coverage adequate
+- E2E tests pass (if applicable)
+- Cross-browser testing (if UI)
+
+**Database & Schema:**
+- Prisma schema validated
+- Migrations tested
+- DBAL conformance tests pass
+
+**Security:**
+- Vulnerabilities checked
+- Input validation implemented
+- No sensitive data committed
+
+**MetaBuilder-Specific:**
+- Data-driven architecture alignment
+- Multi-tenant safety verified
+- Permission checks correct
+- DBAL used (not raw Prisma)
+- Generic components where possible
+
+#### 8. Additional Sections
+- Deployment considerations
+- Reviewer notes
+- Focus areas for review
+
+## Using the Templates
+
+### Creating an Issue
+
+1. Go to the [Issues page](https://github.com/johndoe6345789/metabuilder/issues)
+2. Click "New issue"
+3. Select the appropriate template
+4. Fill in all required fields (marked with red asterisk)
+5. Complete the pre-submission checklist
+6. Submit the issue
+
+### Creating a Pull Request
+
+1. Push your branch to GitHub
+2. Navigate to the repository
+3. Click "Pull requests" → "New pull request"
+4. Select your branch
+5. The PR template will auto-populate
+6. Fill in all sections thoroughly
+7. Mark checkboxes in the pre-submission checklist
+8. Submit the PR
+
+### Template Tips
+
+**For Issues:**
+- Be specific and detailed
+- Include reproduction steps for bugs
+- Provide environment details
+- Search for duplicates first
+- Check documentation before submitting
+
+**For PRs:**
+- Link related issues
+- Include screenshots for UI changes
+- Document breaking changes clearly
+- Run all tests before submitting
+- Complete the entire checklist
+- Focus on minimal, surgical changes
+
+## MetaBuilder-Specific Guidelines
+
+### Data-Driven Architecture
+MetaBuilder is 95% JSON/Lua, not TypeScript. When contributing:
+- Prefer JSON/Lua configuration over hardcoded TS
+- Use `RenderComponent` for declarative UI
+- Add Lua scripts to `packages/*/seed/scripts/`
+- Keep TypeScript as adapters/wrappers
+
+### Multi-Tenancy
+All contributions must respect tenant isolation:
+- Include `tenantId` in all queries
+- Use `Database` class methods, not raw Prisma
+- Test with multiple tenants
+- Document tenant-specific behavior
+
+### Permission System (Levels 1-6)
+- Level 1: Public (no auth)
+- Level 2: User (basic auth)
+- Level 3: Moderator (content moderation)
+- Level 4: Admin (user management)
+- Level 5: God (system config, packages)
+- Level 6: Supergod (full system control)
+
+When adding features, specify the minimum required level and use `canAccessLevel()` checks.
+
+### Package System
+Packages follow strict conventions:
+- Name: `snake_case` (e.g., `blog_engine`)
+- Version: Semver (e.g., `1.2.3`)
+- Structure: `packages/{name}/seed/` with `metadata.json`, `components.json`
+- Lua scripts in `packages/{name}/seed/scripts/`
+- Optional React components in `packages/{name}/src/`
+
+### DBAL (Database Abstraction Layer)
+- TypeScript implementation: `dbal/ts/` (development)
+- C++ implementation: `dbal/cpp/` (production)
+- YAML contracts: `api/schema/` (source of truth)
+- Always update YAML first
+- Run conformance tests: `python tools/conformance/run_all.py`
+- Ensure both implementations behave identically
+
+## Best Practices
+
+### Issue Reporting
+1. **Search first**: Check if the issue already exists
+2. **Be specific**: Provide exact steps and details
+3. **Be respectful**: Follow the code of conduct
+4. **Be patient**: Maintainers will respond when available
+5. **Follow up**: Provide additional info if requested
+
+### Pull Requests
+1. **Small changes**: Keep PRs focused and minimal
+2. **Test thoroughly**: Run all tests and linters
+3. **Document well**: Update docs with changes
+4. **Follow conventions**: Match existing code style
+5. **Respond quickly**: Address review feedback promptly
+
+### Security
+- **Never commit secrets**: No API keys, passwords, tokens
+- **Report privately**: Use GitHub Security Advisories for vulnerabilities
+- **Hash passwords**: Always use SHA-512 via `password-utils.ts`
+- **Validate input**: Never trust user input
+- **Sandbox Lua**: Maintain Lua script restrictions
+
+## Getting Help
+
+If you have questions about the templates or contribution process:
+
+1. **Documentation**: Check [docs/](../docs/) for guides
+2. **Discussions**: Ask in [GitHub Discussions](https://github.com/johndoe6345789/metabuilder/discussions)
+3. **Examples**: Look at existing issues and PRs
+4. **Workflow Guide**: See `.github/prompts/0-kickstart.md`
+
+## Template Maintenance
+
+These templates are living documents. If you find:
+- Missing fields or options
+- Unclear instructions
+- Better ways to structure
+- New categories needed
+
+Please submit an issue with the "documentation" template to suggest improvements!
+
+## Related Files
+
+- **Workflow Guide**: `.github/prompts/0-kickstart.md`
+- **Contributing**: `README.md` → Contributing section
+- **Architecture**: `docs/architecture/`
+- **DBAL Guide**: `dbal/AGENTS.md`
+- **UI Standards**: `UI_STANDARDS.md`
+- **Copilot Instructions**: `.github/copilot-instructions.md`
--- a/README.md
+++ b/README.md
@@ -1038,9 +1038,21 @@ npm run start

 ## Contributing

+### Reporting Issues
+
+MetaBuilder uses structured issue templates to ensure quality bug reports and feature requests:
+
+- **🐛 Bug Report**: Report bugs with environment details and reproduction steps
+- **✨ Feature Request**: Propose features aligned with data-driven architecture
+- **📚 Documentation**: Request documentation improvements
+- **📦 Package Request**: Propose new packages for the package system
+- **🔧 DBAL Issue**: Report Database Abstraction Layer issues
+
+See [`.github/TEMPLATES.md`](.github/TEMPLATES.md) for detailed guidance on using templates.
+
 ### Workflow

-1. Follow `.github/copilot-instructions.md`
+1. Follow `.github/copilot-instructions.md` and `.github/prompts/0-kickstart.md`
 2. Run `npm run lint:fix` before committing
 3. Add parameterized tests for new functions
 4. Commit with descriptive messages on `main`
@@ -1063,10 +1075,15 @@ npm run test:unit -- --run

 PRs are optional (trunk-based on `main` is default). When required:

-1. Run linter and tests
-2. Update documentation
-3. Add test cases
-4. Use descriptive PR title
+1. Use the comprehensive PR template (auto-populated)
+2. Complete all sections and checklists
+3. Include screenshots for UI changes
+4. Run linter and tests
+5. Update documentation
+6. Add test cases
+7. Use descriptive PR title
+
+See [`.github/TEMPLATES.md`](.github/TEMPLATES.md) for the complete PR checklist and MetaBuilder-specific guidelines.

 ---