From a0a8ec7e858a9197e565d81f727623adea6783d6 Mon Sep 17 00:00:00 2001 From: "Mathijs de Bruin (aider)" Date: Fri, 31 Jan 2025 10:15:30 +0000 Subject: [PATCH] Update main README.md, CONTRIBUTING.md and add PR and issue templates. --- .github/ISSUE_TEMPLATE.md | 51 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 39 +++++++ CONTRIBUTING.md | 109 ++++++++++++++---- README.md | 192 ++++++++++++++----------------- 4 files changed, 264 insertions(+), 127 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..3377185 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,51 @@ + + +## Issue Type +- [ ] 🐛 Bug Report +- [ ] 💡 Feature Request +- [ ] 📚 Documentation Issue +- [ ] 🛠️ Development Discussion + +## Environment +- Chainlit Community Version: +- Python Version: +- OS: +- Package Affected: + +## For Bug Reports +### Description + + +### Steps to Reproduce +1. +2. +3. + +### Expected vs Actual Behavior + + +### Relevant Logs/Screenshots + + +## For Feature Requests +### Motivation + + +### Proposed Solution + + +### Alternative Solutions + + +### Impact + + +## Additional Context + + +## Contribution Guidelines +- I agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md) +- I've read the [CONTRIBUTING.md](CONTRIBUTING.md) +- This issue is not a duplicate of existing issues + +> 💡 For general questions, please use our [Discord community](https://discord.gg/k73SQ3FyUh) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..cc0a7c9 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,39 @@ + + +## Description + + + +## Related Issue + + + +Fixes # + +## Type of Change + +- [ ] 🐛 Bug fix +- [ ] ✨ New feature +- [ ] ♻️ Refactoring +- [ ] 📚 Documentation update +- [ ] 🚀 CI/CD improvement +- [ ] ⚠️ Security fix + +## Checklist + +- [ ] ✅ Added/updated tests for changes +- [ ] ✅ Verified CI tests pass locally (`./scripts/ci.sh`) +- [ ] ✅ Updated package documentation (README.md) +- [ ] ✅ Considered Chainlit version compatibility +- [ ] ✅ Followed [Code of Conduct](CODE_OF_CONDUCT.md) + +## Breaking Changes + + + +- [ ] Yes (Please describe) +- [ ] No + +## Additional Notes + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfc3537..56d1e29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,8 @@ # Contributing to Chainlit Community -First off, thank you for considering contributing to the Chainlit Community repository! It's people like you that make Chainlit such a great tool. This document provides guidelines and steps for contributing. Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved. +First off, thank you for considering contributing to the Chainlit Community repository! It's people like you that make +Chainlit such a great tool. This document provides guidelines and steps for contributing. Please take a moment to +review this document in order to make the contribution process easy and effective for everyone involved. ## Table of Contents @@ -17,6 +19,7 @@ First off, thank you for considering contributing to the Chainlit Community repo ### Requirements +- [Python](https://python.org/) 3.10-3.12 - [uv](https://docs.astral.sh/uv/getting-started/installation/) ### Setting up @@ -27,7 +30,53 @@ With uv installed, follow these steps to set up your development environment: 1. Install pre-commit hooks: `uv run pre-commit install --install-hooks` This will enable automatic formatting, syntax checking and fixups for your contributions. -1. Done! +1. Install dependencies: `uv sync --all-packages` + +## 🛠 Development Workflow + +### CI Integration + +Our CI system (GitHub Actions) automatically runs: + +- Formatting checks (Ruff) +- Linting (Ruff) +- Type checking (Pyright) +- Unit tests (pytest) for the latest Chainlit release as well as current `main`, + across all supported Python versions +- Dependency validation + +Verify locally before pushing: + +```bash +./scripts/ci.sh # Runs full test suite +``` + +### Code Quality + +We enforce strict quality controls: + +1. **Formatting**: + ```bash + uv run ruff format . # Auto-format code + ``` +1. **Linting**: + ```bash + uv run ruff check . # Validate code standards + ``` +1. **Type Checking**: + ```bash + uv run pyright # Static type analysis + ``` + +### Commit Hooks + +Pre-commit hooks automatically: + +- Format code with Ruff +- Check linting rules +- Validate package structures + +Hooks run on every commit - no need to manually format! ### Adding packages @@ -48,7 +97,8 @@ With uv installed, follow these steps to set up your development environment: - Feel free to open issues to report bugs, suggest improvements, or propose new features. - Before opening an issue, please check if a similar issue already exists. -- When reporting a bug, include as much detail as possible, including steps to reproduce, expected behavior, and actual behavior. +- When reporting a bug, include as much detail as possible, including steps to reproduce, expected behavior, and + actual behavior. ### Pull Requests @@ -60,31 +110,47 @@ With uv installed, follow these steps to set up your development environment: ## Coding Standards -- We use [Ruff](https://github.com/astral-sh/ruff) for code formatting and linting. Run `ruff check .` and `ruff format .` before committing. +- We use [Ruff](https://github.com/astral-sh/ruff) for code formatting and linting. The commit hooks automatically run + `ruff check .` and `ruff format .` when you commit, but we recommend setting up Ruff and Pyright in your editor. - Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for Python code. - Use type hints wherever possible. - Write descriptive variable and function names. -- Comment your code where necessary, but strive to make it self-documenting. -- For type checking, we use [Pyright](https://github.com/microsoft/pyright). -We strongly recommend setting up Ruff and Pyright in your text editor or IDE. This will help catch potential issues early in the development process. +## Editor Setup + +### General Recommendations + +- Install Ruff & Pyright extensions +- Enable "format on save" +- Set line length to 120 (matches Ruff config) + +### VS Code Specific + +1. Install extensions: + - [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) + - [Pyright](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) +1. Add to settings.json: + ```json + { + "[python]": { + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.formatOnSave": true + }, + "ruff.importStrategy": "fromEnvironment", + "python.analysis.typeCheckingMode": "strict" + } + ``` ## CI/Testing -- Write unit tests for all new code using pytest. -- Aim for at least 80% test coverage for any new code. -- Run the full ci suite locally suite before submitting a pull request: - ``` - ./scripts/ci.sh - ``` -- Tests should be written to work against both the latest Chainlit release and the main branch. +All components maintain full test coverage of their public APIs. When contributing: -## Documentation - -- Update the documentation for any new features or changes to existing functionality. -- Place all documentation in the `docs` folder. -- Use clear, concise language and provide examples where appropriate. -- If you're adding a new feature, include a usage example. +- Add tests for new functionality in `src/tests/` +- Preserve existing test patterns +- Validate against multiple Chainlit versions: + ```bash + uv run pytest --chainlit-version=2.0.4,latest,main + ``` ## Community Expectations @@ -95,6 +161,7 @@ We strongly recommend setting up Ruff and Pyright in your text editor or IDE. Th - Share knowledge and assist others when possible. - Focus on the goals of the project and avoid scope creep. -Remember, contributions to this repository should align with its goals and not replicate core Chainlit functionality. If you're unsure whether your contribution fits, feel free to open an issue for discussion first. +Remember, contributions to this repository should align with its goals and not replicate core Chainlit functionality. If +you're unsure whether your contribution fits, feel free to open an issue for discussion first. Thank you for contributing to Chainlit Community! Your efforts help make Chainlit better for everyone. diff --git a/README.md b/README.md index 587f72c..62bccb1 100644 --- a/README.md +++ b/README.md @@ -1,138 +1,118 @@ # Chainlit Community -Welcome to the Chainlit Community repository! This project extends and enhances the [Chainlit](https://chainlit.io/) ecosystem through community-driven development and maintenance. - [![Discord](https://dcbadge.vercel.app/api/server/ZThrUxbAYw?style=flat)](https://discord.gg/k73SQ3FyUh) -[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/chainlit_io.svg?style=social&label=Follow%20%40chainlit_io)](https://twitter.com/chainlit_io) [![CI](https://github.com/Chainlit/chainlit-community/actions/workflows/ci.yaml/badge.svg)](https://github.com/Chainlit/chainlit-community/actions/workflows/ci.yaml) -## 🌟 About This Project +Community-maintained extensions for [Chainlit](https://chainlit.io/). Provides alternative data layers and storage providers while maintaining full compatibility with Chainlit's core API. -The Chainlit Community repository is a collaborative space for developers to contribute to the broader Chainlit ecosystem. While the [core Chainlit project](https://github.com/Chainlit/chainlit) focuses on essential features and integrations, this repository serves as a hub for community-maintained extensions, plugins, and integrations. +**Quick Links**: -### Current State +- [Component Architecture](#component-architecture) +- [Contribution Guide](CONTRIBUTING.md) +- [Available Packages](#-current-state) -- This repository is separate from the main Chainlit project, allowing for more flexible and community-driven development. -- It hosts a variety of community-contributed extensions and integrations that expand Chainlit's capabilities beyond its core functionality. -- The project is in its early stages, with a growing collection of community contributions. +## 🚀 Project Purpose -### Roadmap +Extend Chainlit's capabilities through community-maintained components: -1. Establish a clear contribution process and guidelines. -1. Develop and maintain a curated list of community extensions and integrations. -1. Implement a review and testing system for contributed code. -1. Create centralized documentation for all sub-projects in the `docs` folder. -1. Regularly synchronize with the core Chainlit project to ensure compatibility. -1. Foster a vibrant community of contributors and users. +- Alternative data persistence layers +- Cloud storage integrations +- Specialized observability solutions +- Testing utilities -### Project Goals +## 🧩 Component Architecture -- Provide a platform for the Chainlit community to extend and enhance the core Chainlit functionality. -- Maintain a high-quality collection of community-driven extensions and integrations. -- Encourage innovation and experimentation within the Chainlit ecosystem. -- Reduce the maintenance burden on the core Chainlit team by distributing responsibility across the community. -- Create a sustainable model for long-term growth and maintenance of the Chainlit ecosystem. -- Foster community collaboration and quality control through shared code reviews, API alignment, and best practices. +### Core Components -### Non-Goals +| Type | Packages | Documentation Links | +| ------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Data Layers** | `dynamodb`, `sqlalchemy`, `literalai` | [DynamoDB](packages/data_layers/dynamodb/README.md), [SQL](packages/data_layers/sqlalchemy/README.md), [Literal](packages/data_layers/literalai/README.md) | +| **Storage Clients** | `azure`, `azure_blob`, `gcs`, `s3` | [Azure](packages/storage_clients/azure/README.md), [GCS](packages/storage_clients/gcs/README.md), [S3](packages/storage_clients/s3/README.md) | +| **Testing** | `pytest` | [Pytest Plugin](packages/pytest/README.md) | -- Replacing or competing with the core Chainlit project -- Implementing core Chainlit features or functionalities -- Providing official support for Chainlit's core features -- Developing commercial products or services +## 🛠️ Getting Started -## 🤝 How to Contribute +### For Users -We welcome contributions from developers of all skill levels. To get started: - -1. Fork this repository and create a new branch for your feature or fix. -1. Develop your contribution, ensuring it follows our coding standards and guidelines. -1. Write tests and documentation for your code. -1. Submit a pull request with a clear description of your changes and their purpose. - -For detailed contribution guidelines, please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) file. - -### Quality Control and Testing - -To maintain high-quality code and reduce technical debt, we enforce the following practices: - -- Extensive use of pytest for automated testing -- Type checking and linting -- Minimum 80% test coverage for new code -- Testing against both the latest Chainlit release and the main branch -- Documentation for all added or changed functionality - -## Component Architecture - -Chainlit Community components follow a modular architecture with two main component types: - -### 1. Data Layers -**Role**: Persistent structured data storage for conversation elements (users, threads, steps) -**Interactions**: -- Direct integration with Chainlit's data layer system -- Optional integration with Storage Providers for file attachments - -| Package | Description | README | -|---------|-------------|--------| -| `dynamodb` | Amazon DynamoDB implementation with cloud storage integration | [docs](packages/data_layers/dynamodb/README.md) | -| `sqlalchemy` | SQL database support (PostgreSQL/SQLite) with storage provider integration | [docs](packages/data_layers/sqlalchemy/README.md) | -| `literalai` | Official Literal AI observability platform integration | [docs](packages/data_layers/literalai/README.md) | - -### 2. Storage Providers -**Role**: File storage and management for attachments/media -**Interactions**: -- Used by Data Layers through dependency injection -- Handle upload/delete operations and URL generation - -| Package | Cloud Provider | README | -|---------|----------------|--------| -| `azure` | Azure Data Lake | [docs](packages/storage_clients/azure/README.md) | -| `azure-blob` | Azure Blob Storage | [docs](packages/storage_clients/azure_blob/README.md) | -| `gcs` | Google Cloud Storage | [docs](packages/storage_clients/gcs/README.md) | -| `s3` | AWS S3 | [docs](packages/storage_clients/s3/README.md) | - -## Typical Data Flow -```mermaid -graph LR - A[Chainlit App] --> B{Data Layer} - B -->|Persists metadata| C[(Database)] - B -->|Delegates files| D[[Storage Provider]] - D -->|Stores objects| E[(Cloud Storage)] +```bash +# Install specific component +pip install chainlit-sqlalchemy[postgres] # SQLAlchemy data layer +pip install chainlit-s3[s3] # AWS S3 storage ``` -## 📚 Documentation +### For Contributors + +1. Fork & clone repo +1. Set up development environment: + +```bash +uv run pre-commit install --install-hooks +uv sync --all-packages +``` + +## 🤝 How to Contribute + +Key Contribution Areas: -All documentation for this repository and its sub-projects is centralized in the `docs` folder. This includes setup instructions, usage guides, and API references for each community-maintained feature or integration. +- New storage providers (Cloudflare R2, MinIO, etc) +- Additional database backends +- Enhanced observability integrations +- Performance optimizations +- Documentation improvements -For general Chainlit documentation, please refer to the [official Chainlit documentation](https://docs.chainlit.io). +**Process**: -## 🔗 Relationship to Core Chainlit +1. Create/claim an issue +1. Develop in dedicated package +1. Add tests & update package README +1. Submit PR with component documentation + +[Full contribution guide →](CONTRIBUTING.md) + +## 🌍 Current State + +**Stable Components** (Full test coverage): + +- SQLAlchemy Data Layer (PostgreSQL/SQLite) +- DynamoDB Data Layer +- AWS S3, GCS, Azure Blob & Data Lake Storage Clients +- Pytest Integration +- LiteralAI Observability + +### Ongoing + +- Maintain compatibility with Chainlit core +- Expand test coverage +- Improve contributor documentation + +## 📚 Documentation -The Chainlit Community repository complements the core Chainlit project by: +Each package maintains its own documentation: -- Providing a space for experimental and specialized features. -- Allowing faster iteration and innovation outside the core product cycle. -- Distributing maintenance responsibilities across the community. +- Implementation guides in package READMEs +- Usage examples in code comments +- Cross-package compatibility notes in [CONTRIBUTING.md](CONTRIBUTING.md) -The core Chainlit project will continue to focus on: +## 🔗 Core Relationship -- Essential features and functionality -- Core LLM framework integrations -- LiteralAI backend integration -- Providing a stable API and hooks for developers to build against +This project extends Chainlit through: -This shared repository structure fosters community collaboration, ensures quality control, and promotes alignment on APIs and best practices. +- Alternative persistence options +- Specialized storage integrations +- Community-driven experimentation -## 📣 Get in Touch +Chainlit Core focuses on: -- Join our [Discord community](https://discord.gg/k73SQ3FyUh) for discussions and support. -- Follow us on [Twitter](https://twitter.com/chainlit_io) for updates. -- Report issues or suggest improvements by creating a [GitHub issue](https://github.com/chainlit-community/chainlit-community/issues). +- Main application logic +- UI/UX components +- Core LLM integrations -## 📄 License +## 📣 Community -This project is licensed under the [Apache 2.0 License](LICENSE). +- [Discord Discussions](https://discord.gg/k73SQ3FyUh) +- [Twitter Updates](https://twitter.com/chainlit_io) +- [Issue Tracker](https://github.com/chainlit-community/chainlit-community/issues) -______________________________________________________________________ +## License -We're excited to see what the community will build with and for Chainlit. Thank you for being a part of this journey! +*Licensed under [Apache 2.0](LICENSE). Community-driven since 2024.*