lyonsil
commented
1 year ago FWIW, ChatGPT says:
When it comes to designing versioning for TypeScript and JavaScript modules, there are several best practices you can follow to ensure smooth compatibility and maintainability. Here are some recommendations:
Semantic Versioning (SemVer): Follow the principles of SemVer for versioning your modules. SemVer consists of three parts:
MAJOR.MINOR.PATCH. Increment theMAJORversion when you make incompatible changes, theMINORversion when you add functionality in a backwards-compatible manner, and thePATCHversion when you make backwards-compatible bug fixes.Git Version Tagging: Utilize Git tags to mark specific versions of your modules. Whenever you release a new version, create a corresponding Git tag with the version number. This allows you to easily track and reference specific releases in your codebase.
Package Managers: If you are using a package manager like npm (Node Package Manager) or yarn, leverage their versioning features. These tools provide commands to manage module versions, publish new releases, and handle dependencies.
Peer Dependencies: Clearly define and manage your module's dependencies, especially peer dependencies. Peer dependencies indicate the compatibility requirements for other modules that may be used alongside your module. Make sure to specify accurate version ranges for peer dependencies to avoid compatibility issues.
Changelogs: Maintain a detailed changelog for each version of your module. Changelogs provide information about the changes made in each release, including bug fixes, new features, and breaking changes. This helps users understand the impact of upgrading to a new version and allows for easier debugging.
Release Notes and Documentation: Alongside your changelog, provide release notes and updated documentation for each version. Clearly explain any breaking changes and provide migration guides if necessary. This assists developers in understanding the changes and adapting their code accordingly.
Testing and Continuous Integration (CI): Implement a robust testing strategy to ensure the stability and compatibility of your modules across different versions. Automated testing, coupled with continuous integration and deployment (CI/CD) pipelines, can help catch potential issues early and prevent regressions.
Deprecation and Sunset Policy: Clearly communicate your deprecation and sunset policy. When you plan to deprecate or remove certain features or modules, provide advance notice and establish a timeline for the deprecation process. This allows users to plan and adapt their code accordingly.
By following these guidelines, you can create a solid versioning strategy for your TypeScript and JavaScript modules, enabling seamless upgrades and better compatibility for your users.
These all seem pretty good to me. Item 1 has some good rules for when to bump versions that matches my experience in the past. Sometimes there is a fourth component which is a build date or date/time that gets used mostly when working with release candidates.
Is there a reason we wouldn't want all of the core repo to carry a unified version?
Versioning a wiki to align with code versioning can be achieved through various approaches. Here are a few common methods:
Git Repository: Store your wiki content in a separate Git repository alongside your codebase. This allows you to leverage the same version control system for both code and documentation. You can create branches, tags, and commits in the wiki repository to correspond with code versions, making it easy to track changes and maintain synchronization.
Documentation as Code: Treat your wiki content as code and version it alongside your codebase within the same repository. Write your documentation using a markup language like Markdown or reStructuredText. By keeping your documentation files in the code repository, you can track changes and version them using the same version control system.
Documentation Branches: Create separate branches in your code repository dedicated to documentation. You can have branches like "master" for the main code and "docs" for the documentation. Each branch can have its own versioning scheme, allowing you to manage and release documentation versions independently.
Release Tags: Use Git tags or release tags to mark specific versions of your codebase, and create corresponding tags for your wiki. This way, you can link each release of your code with a specific version of the wiki. Users can then access the wiki content corresponding to the version of the code they are using.
Documentation Versioning Tools: There are specialized tools available for versioning documentation, such as Read the Docs (https://readthedocs.org/). These tools allow you to create separate versions of your documentation and associate them with specific code versions. They often integrate with popular version control systems like Git and provide a dedicated interface for managing and browsing different versions of your documentation.
Changelog Integration: Include a link to the relevant version of the wiki in your code's changelog or release notes. This ensures that users can easily find the corresponding documentation for each code version.
It's important to choose a method that suits your team's workflow and requirements. Whichever approach you adopt, ensure that your documentation is easily accessible and clearly tied to specific code versions. This enables developers to access the relevant information and helps maintain consistency between the codebase and the accompanying documentation.
This seems a little less obvious to me. I think @FoolRunning has used https://readthedocs.org/ for some scripture burrito work.
tjcouch-sil
FoolRunning
The items on the
papineeds to be versioned. Functions, data types, import statements, etc. All interaction needs to be versioned. We should probably also define some rules for when to bump versions.We also should design how to best version the wiki documentation.
We need to design extension versioning as well for extensions depending on other extensions.