From 39f50aa6d6e7fa375db4090045b3e7be2a918abc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:30:37 +0000 Subject: [PATCH 1/3] Initial plan From 52daeccc37831a3ea36b4c907050132a1a67cd40 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:35:11 +0000 Subject: [PATCH 2/3] Add comprehensive issue and PR templates for MetaBuilder - Created ISSUE_TEMPLATE directory with 6 specialized templates - Bug report template with environment and severity tracking - Feature request template aligned with data-driven architecture - Documentation improvement template - Package request template for MetaBuilder's package system - DBAL-specific issue template for TS/C++ implementations - Configuration file with links to docs and discussions - Comprehensive PR template with architecture checklists - All templates include MetaBuilder-specific considerations: * Multi-tenant safety checks * Permission level targeting (Levels 1-6) * DBAL usage requirements * Data-driven architecture alignment * Package system conventions Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 130 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/dbal_issue.yml | 158 ++++++++++++++ .github/ISSUE_TEMPLATE/documentation.yml | 115 ++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 134 ++++++++++++ .github/ISSUE_TEMPLATE/package_request.yml | 164 ++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 243 +++++++++++++++++++++ 7 files changed, 955 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/dbal_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/package_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..9495d507e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,130 @@ +name: 🐛 Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this bug! Please fill out the form below to help us understand and fix the issue. + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Tell us what went wrong... + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. Scroll down to '...' + 4. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: I expected... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: Instead, I observed... + validations: + required: true + + - type: dropdown + id: component + attributes: + label: Component/Area + description: Which part of MetaBuilder is affected? + options: + - Frontend (Next.js UI) + - Backend (API/Auth) + - Database (Prisma/Schema) + - DBAL (TypeScript/C++) + - Package System + - Lua Scripting + - Multi-Tenant System + - Permission System + - Workflows + - Documentation + - Other + validations: + required: true + + - type: dropdown + id: severity + attributes: + label: Severity + description: How severe is this bug? + options: + - Critical (System crash, data loss) + - High (Major feature broken) + - Medium (Feature partially broken) + - Low (Minor issue, workaround exists) + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Please provide your environment details + value: | + - OS: [e.g., Ubuntu 22.04, macOS 13.0, Windows 11] + - Node Version: [e.g., 18.17.0] + - Browser: [e.g., Chrome 120, Firefox 121] + - Database: [e.g., SQLite, PostgreSQL 15] + render: markdown + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant Logs/Screenshots + description: Add any error logs, screenshots, or console output + placeholder: | + Paste logs here or drag and drop screenshots. + render: shell + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context about the problem + placeholder: | + - Does this happen consistently or intermittently? + - Have you tried any workarounds? + - Did this work in a previous version? + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + description: Please verify the following before submitting + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have provided all required information above + required: true + - label: I have checked the documentation for relevant information + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..fde93ad29 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 📚 Documentation + url: https://github.com/johndoe6345789/metabuilder/tree/main/docs + about: Check our comprehensive documentation for guides and architecture details + - name: 💬 Discussions + url: https://github.com/johndoe6345789/metabuilder/discussions + about: Ask questions and discuss ideas with the community + - name: 🔒 Security Issues + url: https://github.com/johndoe6345789/metabuilder/security/advisories/new + about: Report security vulnerabilities privately diff --git a/.github/ISSUE_TEMPLATE/dbal_issue.yml b/.github/ISSUE_TEMPLATE/dbal_issue.yml new file mode 100644 index 000000000..8917ab823 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/dbal_issue.yml @@ -0,0 +1,158 @@ +name: 🔧 DBAL Issue +description: Report an issue with the Database Abstraction Layer (TypeScript or C++) +title: "[DBAL]: " +labels: ["dbal", "bug", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + DBAL is MetaBuilder's critical database abstraction layer with TypeScript (dev) and C++ (production) implementations. + + - type: dropdown + id: implementation + attributes: + label: DBAL Implementation + description: Which DBAL implementation is affected? + options: + - TypeScript SDK (dbal/ts/) + - C++ Daemon (dbal/cpp/) + - Both implementations + - YAML Contracts (api/schema/) + - Conformance Tests + - Unknown + validations: + required: true + + - type: textarea + id: issue + attributes: + label: Issue Description + description: Describe the DBAL issue you're experiencing + placeholder: The DBAL operation fails when... + validations: + required: true + + - type: dropdown + id: operation + attributes: + label: Operation Type + description: What type of operation is failing? + options: + - Entity Operations (CRUD) + - Query Operations + - Transaction Operations + - Blob Storage + - Key-Value Store + - Tenant Management + - Access Control + - Connection Management + - Type Generation + - Other + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction Code + description: Provide code to reproduce the issue + placeholder: | + ```typescript + // Your code here + const result = await dbalQuery({...}) + ``` + render: typescript + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should happen? + placeholder: The operation should... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happens? + placeholder: Instead, I see... + validations: + required: true + + - type: textarea + id: error + attributes: + label: Error Messages/Logs + description: Include any error messages, stack traces, or logs + render: shell + + - type: dropdown + id: severity + attributes: + label: Severity + options: + - Critical (Data corruption/loss) + - High (Operation completely fails) + - Medium (Operation partially works) + - Low (Minor inconsistency) + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment Details + value: | + - DBAL Version: [e.g., commit hash or version] + - Node/C++ Version: [e.g., Node 18.17, gcc 11.3] + - Database: [e.g., SQLite, PostgreSQL 15] + - OS: [e.g., Ubuntu 22.04] + render: markdown + validations: + required: true + + - type: dropdown + id: parity + attributes: + label: Implementation Parity + description: If both implementations exist, do they behave the same? + options: + - Both implementations fail + - Only TypeScript fails + - Only C++ fails + - Different behavior between implementations + - Haven't tested both + - N/A (only one implementation exists) + + - type: textarea + id: conformance + attributes: + label: Conformance Test Status + description: Do conformance tests pass for this operation? + placeholder: | + - Ran: python tools/conformance/run_all.py + - Result: [Pass/Fail details] + + - type: textarea + id: additional + attributes: + label: Additional Context + description: YAML contract issues? Schema problems? Performance concerns? + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have checked the YAML schema definitions in api/schema/ + required: true + - label: I have verified this isn't a tenant isolation issue + required: true + - label: I have checked conformance test results if applicable + required: false diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 000000000..dec68d3d1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,115 @@ +name: 📚 Documentation +description: Report an issue with documentation or request documentation improvements +title: "[Docs]: " +labels: ["documentation", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for helping improve MetaBuilder's documentation! Clear docs help everyone. + + - type: dropdown + id: doc-type + attributes: + label: Documentation Type + description: What kind of documentation issue is this? + options: + - Missing documentation + - Incorrect/outdated information + - Unclear explanation + - Broken links + - Typo/grammar + - Code example not working + - Missing code example + - Architecture documentation + - API documentation + - Other + validations: + required: true + + - type: textarea + id: location + attributes: + label: Documentation Location + description: Where is the documentation issue? (provide file path, URL, or section name) + placeholder: | + File: docs/architecture/packages.md + Or URL: https://github.com/johndoe6345789/metabuilder/tree/main/docs + Or Section: "Getting Started > Database Setup" + validations: + required: true + + - type: textarea + id: issue + attributes: + label: Issue Description + description: What's wrong with the current documentation? + placeholder: The current documentation states... but it should... + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested Improvement + description: How should the documentation be improved? + placeholder: | + The documentation should instead explain... + Or: Add a section that covers... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Documentation Area + description: Which area of MetaBuilder does this documentation cover? + options: + - Getting Started + - Architecture + - API Reference + - Package System + - DBAL + - Permission System + - Multi-Tenancy + - Lua Scripting + - Workflows + - Database/Prisma + - Testing + - Deployment + - Contributing + - Security + - Other + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other relevant information + placeholder: | + - Screenshots of confusing sections + - Related issues or PRs + - Why this improvement is needed + + - type: checkboxes + id: contribution + attributes: + label: Contribution + description: Would you like to help improve this documentation? + options: + - label: I am willing to submit a PR to fix/improve this documentation + required: false + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have searched existing issues for similar documentation requests + required: true + - label: I have verified the documentation issue still exists in the latest version + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..4c14daa84 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,134 @@ +name: ✨ Feature Request +description: Suggest a new feature or enhancement for MetaBuilder +title: "[Feature]: " +labels: ["enhancement", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for your interest in improving MetaBuilder! Please describe your feature request in detail. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: Is your feature request related to a problem? Describe what you're trying to achieve. + placeholder: I'm frustrated when... / I need to be able to... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see + placeholder: I would like MetaBuilder to... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Have you considered any alternative solutions or workarounds? + placeholder: I've tried... but... + + - type: dropdown + id: component + attributes: + label: Component/Area + description: Which part of MetaBuilder would this feature affect? + options: + - Frontend (Next.js UI) + - Backend (API/Auth) + - Database (Prisma/Schema) + - DBAL (TypeScript/C++) + - Package System + - Lua Scripting + - Multi-Tenant System + - Permission System (Levels 1-6) + - Workflows + - Documentation + - Developer Experience + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - High (Blocker for my use case) + - Medium (Would be very helpful) + - Low (Nice to have) + validations: + required: true + + - type: dropdown + id: user-level + attributes: + label: Target User Level + description: Which permission level(s) would use this feature? + multiple: true + options: + - Level 1 (Public) + - Level 2 (User) + - Level 3 (Moderator) + - Level 4 (Admin) + - Level 5 (God) + - Level 6 (Supergod) + - All levels + + - type: textarea + id: use-cases + attributes: + label: Use Cases + description: Provide specific use cases or examples of how this feature would be used + placeholder: | + 1. As a [user type], I want to [action] so that [benefit] + 2. When [scenario], this feature would help by [outcome] + + - type: textarea + id: technical + attributes: + label: Technical Considerations + description: Any technical details, implementation ideas, or constraints? + placeholder: | + - This might require changes to... + - Could be implemented using... + - May affect performance of... + + - type: textarea + id: mockups + attributes: + label: Mockups/Examples + description: Add any mockups, diagrams, or examples (drag and drop images or links) + placeholder: Paste images or links here... + + - type: checkboxes + id: contribution + attributes: + label: Contribution + description: Would you be willing to help implement this feature? + options: + - label: I am willing to submit a PR for this feature + required: false + - label: I can help with testing this feature + required: false + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + description: Please verify the following before submitting + options: + - label: I have searched existing issues and discussions for similar requests + required: true + - label: This feature aligns with MetaBuilder's data-driven, multi-tenant architecture + required: true + - label: I have provided sufficient detail for others to understand the request + required: true diff --git a/.github/ISSUE_TEMPLATE/package_request.yml b/.github/ISSUE_TEMPLATE/package_request.yml new file mode 100644 index 000000000..682511b09 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/package_request.yml @@ -0,0 +1,164 @@ +name: 📦 Package Request +description: Request a new package for MetaBuilder's package system +title: "[Package]: " +labels: ["enhancement", "package", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + MetaBuilder's power comes from its data-driven package system. Request a new package here! + + - type: input + id: package-name + attributes: + label: Package Name + description: Proposed name for the package (use snake_case) + placeholder: e.g., blog_engine, task_manager, analytics_dashboard + validations: + required: true + + - type: textarea + id: description + attributes: + label: Package Description + description: What functionality would this package provide? + placeholder: This package would enable users to... + validations: + required: true + + - type: dropdown + id: package-type + attributes: + label: Package Type + description: What type of package is this? + options: + - UI Component/Widget + - Feature Module + - Integration + - Tool/Utility + - Template/Theme + - Data Schema + - Workflow + - Other + validations: + required: true + + - type: dropdown + id: min-level + attributes: + label: Minimum Permission Level + description: What's the minimum user level required to use this package? + options: + - Level 1 (Public - no auth required) + - Level 2 (User - basic authentication) + - Level 3 (Moderator - content moderation) + - Level 4 (Admin - user management) + - Level 5 (God - system configuration) + - Level 6 (Supergod - full system control) + validations: + required: true + + - type: textarea + id: features + attributes: + label: Key Features + description: List the main features this package should include + placeholder: | + - Feature 1: Description + - Feature 2: Description + - Feature 3: Description + validations: + required: true + + - type: textarea + id: use-cases + attributes: + label: Use Cases + description: Describe scenarios where this package would be useful + placeholder: | + 1. A [user type] needs to [action] in order to [goal] + 2. When [scenario], this package would help by [benefit] + + - type: textarea + id: components + attributes: + label: Proposed Components + description: What UI components would this package include? + placeholder: | + - ComponentName1: Description + - ComponentName2: Description + + - type: textarea + id: lua-scripts + attributes: + label: Lua Scripts Needed + description: What Lua scripts would be required? (MetaBuilder is 95% JSON/Lua) + placeholder: | + - initialize.lua: Setup and configuration + - validators.lua: Data validation + - helpers.lua: Utility functions + + - type: textarea + id: schemas + attributes: + label: Database Schemas + description: What database tables/models would be needed? + placeholder: | + - Model1 { field1, field2, ... } + - Model2 { field1, field2, ... } + + - type: textarea + id: dependencies + attributes: + label: Package Dependencies + description: Would this package depend on other packages? + placeholder: | + - @metabuilder/dashboard + - @metabuilder/form_builder + + - type: dropdown + id: multi-tenant + attributes: + label: Multi-Tenant Support + description: Does this package need to be tenant-aware? + options: + - "Yes - Requires tenant isolation" + - "No - Can be global" + - "Optional - Configurable" + validations: + required: true + + - type: textarea + id: similar + attributes: + label: Similar Packages/Inspiration + description: Are there similar packages in other systems or frameworks? + placeholder: | + - System X has a similar feature that... + - This is inspired by... + + - type: checkboxes + id: contribution + attributes: + label: Contribution + options: + - label: I am willing to help develop this package + required: false + - label: I can provide Lua scripts for this package + required: false + - label: I can help with testing this package + required: false + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have searched existing packages to ensure this doesn't already exist + required: true + - label: This package aligns with MetaBuilder's data-driven architecture + required: true + - label: I have considered multi-tenant requirements + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..7728b27a2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,243 @@ +## Description + + + +## Related Issue + + +Fixes # + +## Type of Change + + + +- [ ] 🐛 Bug fix (non-breaking change that fixes an issue) +- [ ] ✨ New feature (non-breaking change that adds functionality) +- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] 📚 Documentation update +- [ ] 🎨 UI/UX improvement +- [ ] ♻️ Code refactoring (no functional changes) +- [ ] ⚡ Performance improvement +- [ ] ✅ Test additions or updates +- [ ] 🔧 Configuration/tooling change +- [ ] 📦 Package system change +- [ ] 🔒 Security fix + +## Component/Area Affected + + + +- [ ] Frontend (Next.js UI) +- [ ] Backend (API/Auth) +- [ ] Database (Prisma/Schema) +- [ ] DBAL (TypeScript/C++) +- [ ] Package System +- [ ] Lua Scripting +- [ ] Multi-Tenant System +- [ ] Permission System (Levels 1-6) +- [ ] Workflows +- [ ] Documentation +- [ ] Testing +- [ ] CI/CD +- [ ] Other: + +## Changes Made + + + +### Code Changes +- +- + +### Database Changes +- [ ] Schema changes (Prisma migrations) +- [ ] Seed data updates +- [ ] DBAL contract changes (YAML) + +### Configuration Changes +- [ ] Environment variables +- [ ] Build configuration +- [ ] Package dependencies + +## Testing + + + +### Test Coverage +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] E2E tests added/updated +- [ ] No tests needed (documentation, config, etc.) + +### Test Commands Run +```bash +# Example: +# npm run lint +# npm run typecheck +# npm run test:unit -- --run +# npm run test:e2e +``` + +### Manual Testing + +- [ ] Tested locally +- [ ] Tested in development environment +- [ ] Tested with different user permission levels +- [ ] Tested multi-tenant scenarios + +## Screenshots/Recordings + + + +### Before + + +### After + + +## Architecture & Design Decisions + + + +### Data-Driven Approach +- [ ] Changes follow MetaBuilder's data-driven (JSON/Lua) architecture +- [ ] Declarative components used instead of hardcoded JSX where applicable +- [ ] DBAL used for database operations (not raw Prisma) + +### Multi-Tenancy +- [ ] All queries include `tenantId` filtering +- [ ] Tenant isolation verified +- [ ] N/A - No database queries + +### Permission System +- [ ] Permission checks implemented at correct levels +- [ ] AuthGate or canAccessLevel used where needed +- [ ] N/A - No permission-sensitive features + +### Package System +- [ ] Package metadata follows correct structure (metadata.json, components.json) +- [ ] Package uses snake_case naming and semver versioning +- [ ] Dependencies declared in package metadata +- [ ] N/A - No package changes + +### Security +- [ ] Input validation implemented +- [ ] No XSS vulnerabilities introduced +- [ ] No SQL injection vulnerabilities +- [ ] Passwords hashed with SHA-512 (if applicable) +- [ ] Lua sandbox restrictions maintained (if applicable) +- [ ] No secrets committed to code + +## Breaking Changes + + + +**Breaking Changes:** Yes / No + + + +## Migration Steps + + + +```bash +# Commands needed to migrate: +# npm run db:generate +# npm run db:migrate +``` + +## Documentation + + + +- [ ] README.md updated +- [ ] API documentation updated +- [ ] Architecture docs updated (docs/architecture/) +- [ ] Code comments added/updated +- [ ] Migration guide created (if breaking change) +- [ ] No documentation needed + +## Pre-Submission Checklist + + + +### Code Quality +- [ ] Code follows project conventions (one lambda per file, MUI not Radix/Tailwind) +- [ ] ESLint passes (`npm run lint`) +- [ ] TypeScript compiles (`npm run typecheck`) +- [ ] No console errors or warnings +- [ ] Code is DRY (Don't Repeat Yourself) + +### Testing & Verification +- [ ] All tests pass (`npm run test:unit -- --run`) +- [ ] Test coverage for new code meets standards +- [ ] E2E tests pass (if applicable) +- [ ] Manual testing completed +- [ ] Tested across different browsers (if UI change) + +### Database & Schema +- [ ] Prisma schema validated (`npx prisma validate`) +- [ ] Database migrations tested +- [ ] DBAL conformance tests pass (if DBAL changes) +- [ ] N/A - No database changes + +### Security +- [ ] Security vulnerabilities checked +- [ ] No sensitive data in commits +- [ ] Input validation implemented +- [ ] CSRF/XSS protections in place (if applicable) + +### MetaBuilder-Specific +- [ ] Changes align with data-driven architecture principles +- [ ] Multi-tenant safety verified (tenantId filtering) +- [ ] Permission checks implemented correctly +- [ ] DBAL used instead of raw Prisma (where applicable) +- [ ] Generic components used where possible (RenderComponent) + +### Review +- [ ] Self-reviewed code changes +- [ ] Added TODO comments for deferred work (if any) +- [ ] Commit messages are clear and descriptive +- [ ] PR title is descriptive +- [ ] No unrelated changes included + +## Additional Notes + + + +## Deployment Considerations + + + +- [ ] No special deployment steps needed +- [ ] Requires environment variable changes +- [ ] Requires database migration +- [ ] Requires cache invalidation +- [ ] Requires server restart +- [ ] Other: + +## Reviewer Notes + + + +**Focus Areas:** +- +- + +**Questions for Reviewers:** +- +- + +--- + + From 75e4cea3cd9359b23fc424083bce2af3362aebe7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Dec 2025 03:36:51 +0000 Subject: [PATCH 3/3] 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> --- .github/TEMPLATES.md | 343 +++++++++++++++++++++++++++++++++++++++++++ README.md | 27 +++- 2 files changed, 365 insertions(+), 5 deletions(-) create mode 100644 .github/TEMPLATES.md diff --git a/.github/TEMPLATES.md b/.github/TEMPLATES.md new file mode 100644 index 000000000..781bbcc01 --- /dev/null +++ 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` diff --git a/README.md b/README.md index 79e78b59c..930e0f770 100644 --- 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. ---