Open ajnavarro opened 4 months ago
After attempting to add a VERSION field to various public interfaces, I realized this approach was making the code less readable and generally worse without any real benefit. I propose we consider versioning only after V1, leaving V1 as it is at the final release.
To handle versioning in future major versions, we need to consider the following aspects:
version
MethodUsing the path for versioning allows clients time to update to the latest version while the previous versions remain available in subsequent releases. Versioning via a method (as we are doing right now) will break clients until they update to be compatible with new changes.
Add a VERSION value in the header after a magic word identifying the file format or follow guidelines for the specific storage format used. For example, follow Protobuf/(Amino?) best practices:
Specifically, do not use the same schema for wire and storage.
Avoid having multiple versions for the same data. For instance, if an RPC endpoint is already versioned, adding an extra version for the returned object is unnecessary and discouraged.
Applications control their data storage systems. When a binary is updated, we can detect and initiate a migration process. This is a solved problem for various storage systems:
Summary
We propose implementing versioning across various serialization structures within our application to enhance compatibility, maintainability, and future scalability. This entails versioning in three key areas:
Versioning RPC API:
Implementing versioning in RPC API endpoints by prefixing paths with version numbers (e.g., /api/v1, /api/v2) ensures backward compatibility while allowing for iterative updates and enhancements. This practice enables seamless transitions for clients using different versions of the API and facilitates the graceful evolution of the API over time.
Versioning Data Storage Format:
Introducing versioning to the storage format of our application's data enables smooth migrations when format changes occur. By incorporating version numbers into the data storage mechanism, we ensure that data remains accessible and usable across different versions of the application. This practice is essential for maintaining data integrity and ensuring uninterrupted operation during updates or migrations.
Versioning Data Structures for Inter-Node Communication:
Versioning complex data structures transmitted between nodes enhances interoperability and compatibility across distributed systems. By versioning these data structures, we can accommodate changes and updates without causing disruptions to the communication protocol.
Additional considerations