Merge pull request #52 from johndoe6345789/copilot/create-issue-and-pr-templates

Add issue and PR templates with MetaBuilder-specific validations
This commit is contained in:
2025-12-27 03:58:36 +00:00
committed by GitHub
9 changed files with 1320 additions and 5 deletions

130
.github/ISSUE_TEMPLATE/bug_report.yml vendored Normal file
View File

@@ -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

11
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View File

@@ -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

158
.github/ISSUE_TEMPLATE/dbal_issue.yml vendored Normal file
View File

@@ -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

115
.github/ISSUE_TEMPLATE/documentation.yml vendored Normal file
View File

@@ -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

View File

@@ -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

View File

@@ -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

243
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@@ -0,0 +1,243 @@
## Description
<!-- Provide a clear and concise description of your changes -->
## Related Issue
<!-- Link to the issue this PR addresses -->
Fixes #<!-- issue number -->
## Type of Change
<!-- Mark the relevant option with an "x" -->
- [ ] 🐛 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
<!-- Mark all that apply with an "x" -->
- [ ] 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: <!-- specify -->
## Changes Made
<!-- Provide a detailed list of changes -->
### Code Changes
-
-
### Database Changes
- [ ] Schema changes (Prisma migrations)
- [ ] Seed data updates
- [ ] DBAL contract changes (YAML)
### Configuration Changes
- [ ] Environment variables
- [ ] Build configuration
- [ ] Package dependencies
## Testing
<!-- Describe the tests you ran and their results -->
### 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
<!-- Describe manual testing performed -->
- [ ] Tested locally
- [ ] Tested in development environment
- [ ] Tested with different user permission levels
- [ ] Tested multi-tenant scenarios
## Screenshots/Recordings
<!-- If applicable, add screenshots or recordings to demonstrate UI changes -->
### Before
<!-- Screenshot or description of before state -->
### After
<!-- Screenshot or description of after state -->
## Architecture & Design Decisions
<!-- Document any architectural or design decisions made -->
### 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
<!-- If this PR introduces breaking changes, describe them and migration steps -->
**Breaking Changes:** Yes / No
<!-- If yes, describe:
- What breaks
- Why the change was necessary
- How to migrate existing code/data
- Impact on different user levels
-->
## Migration Steps
<!-- If database migrations or data migrations are needed -->
```bash
# Commands needed to migrate:
# npm run db:generate
# npm run db:migrate
```
## Documentation
<!-- Mark all that apply -->
- [ ] 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
<!-- Verify all items before submitting -->
### 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
<!-- Any additional information, context, or concerns -->
## Deployment Considerations
<!-- Notes for deployment -->
- [ ] No special deployment steps needed
- [ ] Requires environment variable changes
- [ ] Requires database migration
- [ ] Requires cache invalidation
- [ ] Requires server restart
- [ ] Other: <!-- specify -->
## Reviewer Notes
<!-- Specific areas where you'd like reviewer focus -->
**Focus Areas:**
-
-
**Questions for Reviewers:**
-
-
---
<!--
By submitting this PR, I confirm that:
- My contribution follows the project's code of conduct
- I have the right to submit this code
- I understand this will be released under the project's license
-->

343
.github/TEMPLATES.md vendored Normal file
View File

@@ -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`

View File

@@ -1040,9 +1040,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`
@@ -1065,10 +1077,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.
---