Add Date-Based Versioning for Breaking Changes

[schettn]

Description:

To enhance the management of breaking changes in GraphQL schemas, it would be beneficial to implement a versioning system similar to Shopify's approach with dated URLs. This feature will allow automatic creation of new schema versions with date-based routes when backward-incompatible changes are introduced.

Feature Proposal:

1. Date-Based Versioning:

   • Automatic Creation of New Versions: When a breaking change is detected, the development server should prompt the user to create a new version. If confirmed, it will automatically create a new folder structure with a date-based name for the new schema version.

   • Folder Structure:

     • The file structure will be organized as follows:

       ./src/
         ├── 2024-04-04/
         │   ├── index.ts
         │   └── ...
         └── latest/
             ├── index.ts
             └── ...
       

   • New Version Handling:

     • The latest folder will always point to the most recent non-breaking schema version.
     • Older versions (e.g., 2024-04-04) will be retained for backward compatibility and can still be edited or used as needed.

2. Prompt for New Version Creation:

   • Development Server Behavior:
     • When a change that lacks backward compatibility is detected, the Pylon development server should issue a prompt asking whether a new version should be created.
     • If the user chooses to create a new version, the server will:
       1. Generate a new directory with the current date.
       2. Copy or move the relevant schema files into this new directory.
       3. Update routing and configuration to include the new version.

3. Configuration Options:

   • Enable/Disable Versioning:

     • Provide a configuration option to enable or disable this versioning feature. This can be set in a configuration file or via an environment variable.

   • Customizable Date Format:

     • Allow customization of the date format used in the directory names to match different organizational preferences or standards.

4. Benefits:

   • Backward Compatibility: Ensure that existing clients are not broken by introducing breaking changes.
   • Clear Version Management: Make it easier to track and manage different schema versions with clear and organized folder structures.
   • Flexibility: Enable developers to continue working with older versions while rolling out new changes.

5. Implementation Notes:

   • Prompt Logic: The logic for detecting breaking changes and prompting for new versions should be integrated into the schema validation and build process.
   • Documentation: Update documentation to reflect the new versioning system and provide guidance on managing different schema versions.

Additional Information:

Why Automated Date-Based Versioning is Better:

1. Reduced Risk of Human Error:

   • Manual Handling Issues: Managing versions manually during deployment is prone to human error. Developers might forget to create new versions, incorrectly name folders, or miss updating configurations. Automated versioning minimizes these risks by systematically handling version creation and updates.
   • Consistency: Automated date-based versioning ensures a consistent approach to versioning, avoiding discrepancies that can arise from manual processes.

2. Simplified Workflow:

   • Ease of Use: The automated approach simplifies the development workflow by handling versioning tasks automatically. Developers are prompted only when necessary, reducing the cognitive load and making it easier to manage schema changes.
   • Reduced Administrative Overhead: With automated versioning, there is no need to manually track and manage different schema versions during deployment, freeing up time for other critical tasks.

3. Improved Version Tracking:

   • Organized Structure: Date-based versioning provides a clear and organized file structure, making it easy to identify and access different versions of the schema. This structured approach helps in tracking changes and managing API evolution over time.
   • Historical Reference: Keeping historical versions in date-named folders allows for easy reference and rollback if needed. This organized history is more accessible than tracking changes manually.

4. Enhanced Compatibility Management:

   • Backward Compatibility: Automated versioning ensures that breaking changes are handled gracefully by creating new versions. This prevents disruptions for clients relying on the existing schema and maintains backward compatibility automatically.
   • Client Transition: By providing clear versioning, clients can transition to new versions at their own pace, reducing the risk of sudden breaks in their integrations.

5. Reduced Configuration Complexity:

   • Automated Updates: The approach reduces the need to manually update routing and configuration files for each new version. Automated tools handle these updates, ensuring that the latest and previous versions are correctly routed and accessible.
   • Error-Free Configuration: Automated processes help ensure that routing and configurations are accurate, reducing the risk of misconfigurations that can occur with manual updates.

6. Future-Proofing:

   • Scalability: As the API evolves and the number of versions grows, the automated approach scales more efficiently. Manual version management can become cumbersome and error-prone as the number of versions increases.
   • Adaptability: Automated systems can be updated and improved more easily, adapting to new versioning needs or best practices without significant changes to the deployment process.

By adopting an automated date-based versioning system, you gain a more reliable, consistent, and scalable solution for managing schema changes. This approach helps ensure that API evolution is handled smoothly, minimizing disruptions and maintaining high-quality service for API consumers.