dx-skill.md

name	description	license
devex-principles	Guidelines for DevEx development practices extracted from team reviews and discussions. Use when working on DX modules, GitHub Actions, Terraform configurations, or TypeScript code to ensure consistency with PagoPA DevEx principles. Covers modular design, breaking changes, presets, CI/CD best practices, and collaboration workflows.	Complete terms in LICENSE.txt

DevEx Principles Skill

This skill provides guidelines and best practices extracted from the DevEx team's reviews and discussions in pull requests and issues. Following these principles ensures high-quality, maintainable, and idiomatic code within the PagoPA DX ecosystem.

When to Use This Skill

• When designing new Terraform modules or updating existing ones
• When creating GitHub Actions or CI/CD workflows
• When writing TypeScript code or configuring ESLint rules
• When making decisions about breaking changes or API design
• When setting up presets, defaults, or configuration management

Modular Design and Reusability

Reuse Existing Modules

• Rule: Prefer reusing existing modules over creating new ones to avoid duplication.
• Practice: Before creating a new module (e.g., for public app services), check if an existing one can be extended or if separation is truly necessary.
• Example: Discussions on reusing app service modules instead of creating separate ones for public/private variants.

Separation of Concerns

• Rule: Create separate modules for different functionalities to maintain clarity and avoid complexity.
• Practice: For app services, have distinct modules for public vs. private deployments rather than a single module with many conditional variables.
• Goal: Reduce confusion and make modules easier to consume.

Inline vs. Dedicated Configurations

• Rule: Avoid inline configurations for complex resources like APIM products, APIs, and policies.
• Practice: Use dedicated modules or separate XML files for policies to support code generation and easier editing.
• Rationale: Aligns with team practices and simplifies CLI-generated code.

Breaking Changes and Compatibility

Minimize Breaking Changes

• Rule: Be extremely cautious with breaking changes, especially for modules used in production.
• Practice: When renaming resources or changing interfaces, ensure backward compatibility or clear communication.
• Example: Concerns about changing module names or slot configurations that could break existing deployments.

Communication for Changes

• Rule: Document and communicate any potential breaking changes in PR descriptions and discussions.
• Practice: Reference Jira issues and explain migration paths when necessary.

Configuration Management

Use Presets and Defaults

• Rule: Provide presets with default values (e.g., low, standard, high) for common configurations.
• Practice: For autoscaling or resource sizing, offer predefined profiles instead of requiring manual tuning of every parameter.
• Benefit: Simplifies consumption and reduces errors.

Compute Derived Values

• Rule: If you have a resource ID, compute related information internally rather than requiring separate inputs.
• Practice: From app_service_id, derive resource group and subscription details automatically.
• Goal: Minimize required variables and simplify module usage.

CI/CD and GitHub Actions

Handle Concurrency Properly

• Rule: Use concurrency groups to prevent parallel runs where sequential execution is needed.
• Practice: In GitHub Actions, ensure only one job runs at a time for deployments to avoid conflicts.

Document Hidden Requirements

• Rule: Clearly document any hidden requirements or dependencies in pipelines.
• Practice: For swap slot actions, note environment variables like WEBSITE_SWAP_WARMUP_PING_PATH that are needed for proper functionality.
• Rationale: Prevents failures and improves usability.

Version Pinning

• Rule: Pin versions for actions and tools to ensure reproducibility.
• Practice: Avoid latest tags; use specific versions to prevent supply-chain risks.

TypeScript and Coding Standards

Gradual Enforcement

• Rule: Enforce best practices gradually; provide lite vs. strict rule sets.
• Practice: For ESLint, have basic rules for general code quality and stricter ones for specific paradigms.
• Example: Functional programming enforcement only where it improves readability, not universally.

Avoid Forced Paradigms

• Rule: Don't force functional programming or other paradigms in areas where they add complexity.
• Practice: Suitable for frontend or SDK layers, but not mandatory everywhere.
• Balance: Improve readability where possible, but prioritize simplicity.

Terraform Best Practices

Version Management

• Rule: Keep Terraform versions up to date and handle migrations carefully.
• Practice: Update version constraints (e.g., from ~> to newer) and test thoroughly.
• Example: Updating from older versions to 1.9.5 with proper validation.

Drift Detection and Refresh

• Rule: Use appropriate flags like -refresh-only to avoid false drift detections.
• Practice: For resources like Cosmos DB indexes, refresh-only can prevent unnecessary recreates.

Collaboration and Workflows

Branch Naming and PR Management

• Rule: Follow <activity-type>/<activity-name> pattern for branches (e.g., feats/user-authentication).
• Practice: Keep names concise; reference Jira issues in PR titles and descriptions.
• Activity Types: feats, fixes, refactors, chores, docs.

Issue and PR References

• Rule: Reference tracking system issues (e.g., Jira) in PR descriptions.
• Practice: Use keywords like "Resolves DX-1234" on separate lines.

Code Reviews and Feedback

• Rule: Encourage thorough reviews and provide detailed feedback.
• Practice: Tag relevant team members (@pagopa/engineering-team-devex) for decisions.
• Goal: Ensure quality and alignment with principles.

References

• DevEx Comments Archive - Source of extracted principles
• General Instructions - Overall project guidelines
• TypeScript Instructions - Language-specific rules