Upgrade Doks
This guide covers how to update your version of Doks and related dependencies, how to learn what has changed from one version to the next, and how to understand Doks’ versioning system and corresponding documentation updates.
What has changed?
See all release notes or the latest release notes.
You can find an exhaustive list of all changes in Doks’ changelog, and important instructions for upgrading to each new major version in our upgrade guides.
Upgrade to the latest version
To update Doks and integrations to their current versions, use the appropriate command for your package manager. For example, upgrade Doks with Images and SEO integrations:
Install a specific version
To install a specific version of Doks or integrations, use the appropriate command for your package manager.
Documentation updates
This documentation is updated for each minor release and major version release. When new features are added, or existing usage changes, the docs will update to reflect the current behavior of Doks. If your project is not updated, then you may notice some behaviors do not match the up-to-date documentation.
New features are added to docs with the specific version number in which they were added. This means that if you have not updated to the latest release of Doks, some documented features may be unavailable. Always check the Added in: version number and make sure your project is updated before attempting to use new features!
If you have not upgraded to the latest major version of Doks, you may encounter significant differences between the Doks documentation and your project’s behavior. We strongly recommend upgrading to the current major version of Doks as soon as you are able. Both the code and the documentation for earlier versions is unsupported.
Upgrade Guides
After every major version release, you will find an upgrade guide with information about important changes and instructions for upgrading your project code.
The main Doks documentation pages are always accurate for the latest released version of Doks. They do not describe or compare to how things worked in previous versions, nor do they highlight updated or changed behavior.
See the upgrade guides below for an explanation of changes, comparing the new version to the old. The upgrade guides include everything that could require you to change your own code: breaking changes, deprecations, feature removals and replacements as well as updated usage guidance. Each change to Doks includes a “What should I do?” section to help you successfully update your project code.
Older docs (unmaintained)
Documentation for older versions of Doks is not maintained, but is available as a static snapshot. Use these versions of docs if you are unable to upgrade your project, but still wish to consult guides and reference:
Semantic versioning
Doks attempts to adhere as much as possible to semantic versioning, which is a set of rules developers use to determine how to assign a version number to a release. Semantic version follows a predictable pattern to inform users of the kind of changes they can expect from one version to the next.
Semantic versioning enforces a pattern of X.Y.Z for software version numbers. These values represent major (X), minor (Y), and patch (Z) updates.
Patch changes
Patch changes are the least disruptive changes. They do not change the way you use Doks, and no change to your own code is required when you update.
When Doks issues a “patch” version, the last number increases. (e.g. @hyas/doks-core@1.6.0 -> @hyas/doks-core@1.6.1)
Patches may be released for reasons such as:
- Internal changes that do not change Doks’ functionality:
- refactors
- performance improvements
- increase or change in test coverage
- aligning with stated documentation and expected behavior
- Improvements to logging and error messages.
- Re-releases after a failed release.
Patch changes also include most bug fixes, even in cases where users were taking advantage of existing unintended or undesirable behavior.
Minor changes
Minor releases primarily introduce new features and improvements that you may wish to try, but require no changes to your code. Some existing features may also be deprecated (marked for deletion in a future version while continuing to function) in a minor release, giving you the opportunity to prepare for their eventual removal.
Minor releases include changes such as:
- Deprecations of existing features/options with a warning that they will be removed in an upcoming major release.
- Introduction of new functionalities.
- Introduction of new options in the integration hooks.
A minor release may also include smaller, patch changes at the same time.
Major changes
Major releases will include breaking changes to at least some existing code. These breaking changes are always documented in an “Upgrade to vX” guide in Doks.
Major releases allow Doks to make significant changes not only to internal logic, but also to intended behavior and usage. Documentation will be updated to reflect the latest version only, and static, unmaintained snapshots of older docs are available as a historical record for older projects that are not yet upgraded.
Major releases include changes such as:
- Removal of previously deprecated functionalities.
- Changes of existing functionalities.
- Changes of existing options in the integration hooks.
A major release may also include some non-breaking changes and improvements that would normally be released separately in a minor or patch release.