@devix-tecnologia/directus-extension-inframe

# Contributing to Directus Extension inFrame Thank you for your interest in contributing! This guide will help you set up your development environment and understand our workflow. ## 🛠️ Development Setup ### Prerequisites - Node.js 18+ - pnpm (recommended) or npm - Docker and Docker Compose (for testing) - Git ### Getting Started 1. **Fork and clone the repository:** ```bash git clone https://github.com/YOUR_USERNAME/directus-extension-inframe.git cd directus-extension-inframe ``` 2. **Install dependencies:** ```bash pnpm install ``` 3. **Build the extension:** ```bash pnpm build ``` ## 🧪 Testing This extension includes automated tests that verify compatibility with different versions of Directus. ### Test Structure ``` tests/ ├── index.spec.ts # Main integration tests ├── setup-hook.spec.ts # Auto-setup system tests ├── setup.ts # Test environment configuration ├── helper_test.ts # Helper functions ├── test-env.ts # Environment variables ├── test-logger.ts # Logging system └── directus-versions.js # Tested versions ``` ### Running Tests ```bash # Run all tests pnpm test # Test with a specific Directus version DIRECTUS_TEST_VERSION=11.13.1 pnpm test # Check formatting and types pnpm lint pnpm typecheck ``` ### Clean Test Containers ```bash # Remove all test containers docker rm -f $(docker ps -aq --filter "name=directus-inframe") 2>/dev/null docker network prune -f ``` ### Tested Directus Versions Tests run on the following versions: - **Directus 9.x**: 9.22.4, 9.23.1, 9.24.0 - **Directus 10.x**: 10.8.3 - **Directus 11.x**: 11.13.1 and newer **Note:** Directus 11.10.1 has known issues and is blocked in tests. ### Test Architecture Tests use: - ✅ **Docker Compose** for isolated environment - ✅ **Vitest** for test execution - ✅ **SQLite** for test database - ✅ **Docker exec** for HTTP communication (no port mapping) - ✅ **Parallel tests** with `maxConcurrency: 3` - ✅ **Generous timeouts** (300s) for slow containers #### Communication via Docker Exec Tests use `docker exec` to make HTTP requests directly inside the container, eliminating the need for port mapping and allowing safe parallel execution of multiple versions simultaneously. ## 🏗️ Project Structure ``` src/ ├── index.ts # Main module definition ├── List.vue # Main list component ├── types.ts # TypeScript type definitions ├── shims.d.ts # Vue type declarations ├── components/ │ ├── ItemDetail.vue # Item detail component │ └── NavMenu.vue # Navigation menu component └── utils/ └── useFetchItems.ts # Composable for fetching data ``` ## 📝 Code Standards ### TypeScript - Always use strict typing - Define interfaces for complex objects in `types.ts` - Use Directus types when available (`@directus/types`) ### Vue 3 - **ALWAYS** use Composition API with `<script setup>` - Use composables for reusable logic (pattern `use*`) - Components should have PascalCase names - Props must be typed with TypeScript interfaces ### Naming Conventions - Component files: PascalCase (e.g., `ItemDetail.vue`) - Composables: camelCase starting with "use" (e.g., `useFetchItems.ts`) - Variables and functions: camelCase - Constants: UPPER_SNAKE_CASE - Interfaces: PascalCase with optional "I" prefix ### Vue Component Structure ```vue <template>  </template> <script setup lang="ts"> // Imports // Props/Emits definitions // Composables usage // Reactive data // Computed properties // Methods // Lifecycle hooks </script> <style scoped> /* Component-specific styles */ </style> ``` ## 🔄 Development Workflow ### Available Scripts ```bash pnpm build # Build for production pnpm dev # Build in development mode with watch pnpm lint # Check code with ESLint pnpm lint:fix # Auto-fix ESLint issues pnpm format # Format code with Prettier pnpm format:check # Check formatting pnpm typecheck # TypeScript type checking pnpm test # Run tests ``` ### Local Development with Directus 1. **Start a local Directus instance:** ```bash docker compose up -d ``` 2. **Configure CSP to allow iframes:** The provided `docker-compose.yml` is configured to allow iframes from any domain (for development): ```yaml CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC: '*' ``` > [!WARNING] In production, configure CSP to allow only trusted domains. 3. **Build the extension in watch mode:** ```bash pnpm dev ``` 4. **The extension will be automatically reloaded** when you make changes. ## 🔄 CI/CD & Automated Updates ### Dependency Management with Renovate This project uses **Renovate** for automated dependency updates with age filtering: - 📦 **npm packages**: Checked weekly on Mondays at 6 AM (São Paulo timezone) - 🕐 **Age filtering**: Packages must be at least **5 days old** before being adopted - 🎯 **Auto-grouping**: Minor and patch updates are grouped together - 🔒 **Security patches**: Applied immediately (0 days) **Age filtering by dependency type:** - Production dependencies: 5 days minimum - Dev dependencies: 3 days minimum - Major updates: 7 days minimum - Directus packages: 5 days minimum - Security patches: 0 days (immediate) > To enable Renovate: Install the [Renovate GitHub App](https://github.com/apps/renovate) on your repository. > Configuration is already in `renovate.json`. ### Directus Version Testing Strategy The project automatically tests against multiple Directus versions to ensure compatibility. To prevent issues with newly released versions, we implement a **version age filter**: - **Default**: New Directus versions are only adopted after **5 days** from their release date - **Configurable**: Adjust via GitHub repository variable `DIRECTUS_VERSION_MIN_AGE_DAYS` #### Why Age Filtering Matters - ✅ **Stability**: Avoids immediate adoption of versions with potential critical bugs - ✅ **Safety**: Gives time for the community to identify breaking changes - ✅ **Reliability**: Ensures patches and hotfixes are released before we test against them ### Configuration #### 1. PAT Token (Recommended - Enables Automated CI) **Status**: Optional, but highly recommended for full automation. **Without PAT_TOKEN**: PRs will be created automatically, but CI tests won't run (you'll need to manually verify). **With PAT_TOKEN**: PRs will be created AND tests will run automatically before merge. To enable automated CI tests on version update PRs: 1. Go to **GitHub.com** → Your profile **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)** 2. Click **Generate new token** with permissions: - ✓ `repo` (all) - ✓ `workflow` 3. Copy the token and add it to your repository: - Repository **Settings** → **Secrets and variables** → **Actions** → **New repository secret** - Name: `PAT_TOKEN` - Value: paste your token > **Why?** GitHub's security prevents `GITHUB_TOKEN` from triggering workflows to avoid infinite loops. A PAT bypasses > this limitation. #### 2. Version Age Filter (Optional) To customize the minimum age for Directus versions: 1. Go to repository **Settings** → **Secrets and variables** → **Actions** → **Variables** tab 2. Click **New repository variable**: - Name: `DIRECTUS_VERSION_MIN_AGE_DAYS` - Value: `5` (or any number of days you prefer) **Recommended values:** - Conservative: `14` days - Balanced: `5` days (default) - Aggressive: `3` days ## 📋 Pull Request Process 1. **Create a feature branch:** ```bash git checkout -b feature/amazing-feature ``` 2. **Make your changes** following our code standards 3. **Run tests and linting:** ```bash pnpm lint pnpm typecheck pnpm test ``` 4. **Commit your changes** using semantic commits: ```bash git commit -m "feat: add amazing feature" ``` See [Semantic Commits](#semantic-commits) below. 5. **Push to your fork:** ```bash git push origin feature/amazing-feature ``` 6. **Open a Pull Request** with a clear description of the changes ## 📝 Semantic Commits Use semantic commits with messages in **English**. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard: ### Format ``` <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` ### Commit Types - **feat**: New feature - **fix**: Bug fix - **docs**: Documentation changes - **style**: Code style changes (formatting, etc.) - **refactor**: Code changes that neither fix bugs nor add features - **perf**: Performance improvements - **test**: Adding or fixing tests - **chore**: Changes to build tools, dependencies, etc. - **ci**: Changes to CI/CD files ### Examples ```bash feat: add advanced filter component fix: correct iframe rendering on mobile devices docs: update README with installation instructions style: apply prettier formatting to components refactor: reorganize utils folder structure perf: optimize API data loading test: add unit tests for NavMenu chore: update project dependencies ci: configure automatic deploy workflow ``` ### Breaking Changes For breaking changes, add `!` after the type or include `BREAKING CHANGE:` in the footer: ```bash feat!: remove support for Directus v9 feat: add new API BREAKING CHANGE: the new API is not compatible with previous versions ``` ## 🐛 Reporting Issues When reporting issues, please include: - Directus version - Extension version - Steps to reproduce - Expected behavior - Actual behavior - Screenshots (if applicable) - Browser/environment details ## 💡 Suggesting Features We love feature suggestions! Please: 1. Check if the feature already exists 2. Check if it's already been suggested in Issues 3. Open a new issue with the "enhancement" label 4. Clearly describe the use case and benefits ## 📄 License By contributing, you agree that your contributions will be licensed under the MIT License. ## 🙏 Questions? Feel free to open an issue or contact us: - **Sidarta Veloso** - [GitHub](https://github.com/sidartaveloso) | [LinkedIn](https://www.linkedin.com/in/sidartaveloso) - **Fernando Gatti** - [GitHub](https://github.com/gattifernando) | [LinkedIn](https://www.linkedin.com/in/gattifernando/) --- Thank you for contributing! 🎉