diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..ff881c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,112 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the form below with as much detail as possible. + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of the bug + placeholder: Describe what went wrong... + validations: + required: true + + - type: textarea + id: reproduce + 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 you expected to happen + placeholder: Describe the expected behavior... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened + placeholder: Describe what actually happened... + validations: + required: true + + - type: dropdown + id: component + attributes: + label: Component + description: Which component is affected? + options: + - Backend API + - Frontend UI + - CLI Tool + - Documentation + - Docker/Deployment + - LakeFS Integration + - S3/Storage + - Authentication + - Organizations + - Other + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Please provide your environment details + placeholder: | + - OS: [e.g. Ubuntu 22.04, Windows 11, macOS 14] + - Python Version: [e.g. 3.10, 3.11] + - Node.js Version: [e.g. 18.x, 20.x] + - Docker Version: [e.g. 24.0.0] + - Deployment: [e.g. Docker, Local Development] + - Browser (if UI issue): [e.g. Chrome 120, Firefox 121] + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs and Error Messages + description: Relevant logs or error messages + placeholder: | + Paste any relevant logs or error messages here. + Use docker-compose logs -f hub-api for backend logs. + render: shell + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any additional information that might help + placeholder: Screenshots, configuration files, related issues, etc. + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have provided all requested information + required: true + - label: I am using the latest version of KohakuHub + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..cc6e05b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Discord Community + url: https://discord.gg/xWYrkyvJ2s + about: Join our Discord server for quick help and discussions + - name: Documentation + url: https://github.com/KohakuBlueleaf/KohakuHub/tree/main/docs + about: Read the documentation for setup guides and API reference diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..c3829f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,105 @@ +name: Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! Please describe your idea in detail. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? + placeholder: Describe the problem or limitation you're facing... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: How would you like this to work? + placeholder: Describe your proposed solution... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What alternative solutions have you considered? + placeholder: Describe any alternative approaches you've considered... + + - type: dropdown + id: component + attributes: + label: Component + description: Which component would this feature affect? + options: + - Backend API + - Frontend UI + - CLI Tool + - Documentation + - Docker/Deployment + - LakeFS Integration + - S3/Storage + - Authentication + - Organizations + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Low - Nice to have + - Medium - Would improve workflow + - High - Blocking current work + validations: + required: true + + - type: textarea + id: use-case + attributes: + label: Use Case + description: Describe your use case for this feature + placeholder: | + Who will benefit from this feature? + How will it be used? + What value does it provide? + validations: + required: true + + - type: textarea + id: examples + attributes: + label: Examples + description: Any examples, mockups, or code snippets + placeholder: | + Provide examples of how this feature would work, + including API examples, UI mockups, or code snippets. + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any additional information + placeholder: Links to related projects, similar features in other tools, etc. + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have checked the roadmap in CONTRIBUTING.md + required: true + - label: I am willing to help implement this feature + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..c6b94cb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,70 @@ +name: Question / Help +description: Ask a question or get help +title: "[Question]: " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + Have a question? We're here to help! + + **Note:** For quick answers, consider joining our [Discord](https://discord.gg/xWYrkyvJ2s)! + + - type: textarea + id: question + attributes: + label: Question + description: What would you like to know? + placeholder: Ask your question here... + validations: + required: true + + - type: dropdown + id: category + attributes: + label: Category + description: What is your question about? + options: + - Setup / Installation + - Configuration + - API Usage + - CLI Usage + - Frontend Development + - Backend Development + - Deployment + - Authentication / Permissions + - Organizations + - Performance / Optimization + - Troubleshooting + - Other + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context + description: Additional context about your question + placeholder: | + What are you trying to accomplish? + What have you tried so far? + Any relevant configuration or setup details? + + - type: textarea + id: environment + attributes: + label: Environment (if relevant) + placeholder: | + - OS: [e.g. Ubuntu 22.04] + - Python Version: [e.g. 3.10] + - Deployment: [e.g. Docker, Local] + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission Checklist + options: + - label: I have checked the documentation + required: true + - label: I have searched existing issues + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..49dd12b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,182 @@ +# Pull Request + +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Test coverage improvement +- [ ] Build/CI improvement + +## Component + + + +- [ ] Backend API +- [ ] Frontend UI +- [ ] CLI Tool +- [ ] Documentation +- [ ] Docker/Deployment +- [ ] Database +- [ ] Authentication +- [ ] LakeFS Integration +- [ ] S3/Storage + +## Related Issues + + + +- Fixes # +- Related to # + +## Changes Made + + + +- +- +- + +## Testing + + + +### Test Environment +- [ ] Local development setup +- [ ] Docker deployment +- [ ] Both + +### Test Scenarios + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing performed +- [ ] Tested in both light and dark mode (for UI changes) +- [ ] Tested on mobile viewport (for UI changes) + +### Test Results + + +``` +# Paste relevant test output here +``` + +## Screenshots / Videos + + + +### Before + + +### After + + +## Documentation + +- [ ] Code is self-documenting and follows project conventions +- [ ] Docstrings/comments added for complex logic +- [ ] README.md updated (if needed) +- [ ] CLAUDE.md updated (if needed) +- [ ] API.md updated (if API changes) +- [ ] CLI.md updated (if CLI changes) +- [ ] CONTRIBUTING.md updated (if workflow changes) + +## Code Quality + +- [ ] Code follows the style guidelines (see [CLAUDE.md](../CLAUDE.md)) +- [ ] Python code formatted with `black` +- [ ] Frontend code formatted with `prettier` +- [ ] Used `db_async` wrappers for all database operations +- [ ] Permission checks added for write operations +- [ ] Error handling follows HuggingFace-compatible format +- [ ] Import order follows convention (builtin → 3rd party → ours) +- [ ] No debug code or commented-out code left in +- [ ] Type hints added (Python) or JSDoc comments (JavaScript) + +## Breaking Changes + + + +- [ ] This PR includes breaking changes + +### Migration Guide + + +## Security Considerations + + + +- [ ] This PR introduces security-sensitive changes +- [ ] Authentication/authorization logic changed +- [ ] Input validation added/updated +- [ ] SQL injection prevention verified +- [ ] XSS prevention verified + +## Performance Impact + + + +- [ ] No performance impact +- [ ] Performance improved +- [ ] Performance may be impacted (explain below) + +### Performance Details + + +## Deployment Notes + + + +- [ ] No special deployment steps required +- [ ] Database migration required +- [ ] Environment variables changed +- [ ] Docker image rebuild required +- [ ] Configuration file updates needed + +### Deployment Steps + + +1. +2. + +## Checklist + + + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] I have read the [CLAUDE.md](../CLAUDE.md) developer guide +- [ ] My code follows the project's coding standards +- [ ] I have tested my changes thoroughly +- [ ] I have added/updated tests as necessary +- [ ] I have updated documentation as necessary +- [ ] My changes generate no new warnings or errors +- [ ] All existing tests pass +- [ ] I have checked my code for security issues +- [ ] I have added myself to CONTRIBUTORS.md (if applicable) + +## Additional Notes + + + +## Reviewer Notes + + + +--- + +**For Maintainers:** + +- [ ] Code review completed +- [ ] Tests pass +- [ ] Documentation is adequate +- [ ] Ready to merge diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75feaea..6f396ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,7 @@ npm install --prefix ./src/kohaku-hub-ui # Start with Docker cp docker-compose.example.yml docker-compose.yml +# IMPORTANT: Edit docker-compose.yml to change default passwords and secrets ./deploy.sh ``` @@ -44,18 +45,25 @@ cp docker-compose.example.yml docker-compose.yml ### Backend (Python) Follow [CLAUDE.md](./CLAUDE.md) principles: -- Modern Python (match-case, async/await, native types) -- Import order: builtin → 3rd party → our package (alphabetical) -- Use `db_async` wrappers for all DB operations -- Split large functions into smaller ones +- Modern Python (match-case, async/await, native types like `list[]`, `dict[]`) +- Import order: **builtin → 3rd party → ours**, then **shorter paths first**, then **alphabetical** + - `import os` before `from datetime import` + - `from kohakuhub.db import` before `from kohakuhub.auth.dependencies import` +- **ALWAYS** use `db_async` wrappers for all DB operations (never direct Peewee in async code) +- Split large functions into smaller ones (especially match-case with >3 branches) +- Use `black` for code formatting +- Type hints recommended but not required (no static type checking) ### Frontend (Vue 3) Follow [CLAUDE.md](./CLAUDE.md) principles: -- JavaScript only (no TypeScript), use JSDoc for types +- JavaScript only (no TypeScript), use JSDoc comments for type hints +- Vue 3 Composition API with ` + + +``` ## Community