Understanding Releases and Notes
Our release notes contain detailed information about the release, including:
Change Log — key changes to the product functionality
Improvements — new features added to the product to extend functionality
Bug Fixes — bug fixes addressing previous functionality
UI Changes — changes to the user interface
API Changes — changes to the APIs (e.g. GraphQL) that may alter integrations
Configuration Changes — differences in the configurable settings
Upgrade Compatibility — basic release compatibility and advice for upgrades
Organization and Grouping
Release note entries are automatically structured according to their type (bug, feature, etc.) and their individual class (grouping), automatically sorted according to the priority of the entries, and marked up where appropriate to highlight entries that are more important or significant than others.
The two different groups are nested; first grouped by the issue type and then by class. For example, all bugs are listed together, and then groups of bugs related to the UI, or API, are grouped together.
The following types of release note, and their markup, are provided below:
Improvements, new features and functionality
The following classes of release note entries are provided:
Installation and Deployment
Falcon Data Replicator
Automation and Alerts
Dashboards and Widgets
Deprecation, Removal, and Breaking Changes
On occasion, changes to LogScale may need to be made that remove features or that are are considered Breaking Changes. These indicate significant changes to the operation of LogScale that are required to support new functionality or behavior or to ensure the security or reliability of LogScale. These include:
Changes to the current behaviour of a feature. For example, changing the way a function operates
Changes to the errors, responses or reactions to certain functions. For example, raising an error in place or a warning
Changing the format or compatibility of a file or file format
Removal of a feature or function
When an item that fits these criteria has been identified:
If the item is a deprecation (i.e. planned removal of functionality) then an item will be added to the release notes identifying the deprecation.
If the item is a breaking change, a Pre Warning entry will be added to the release notes, indicating the feature or functionality will be altered.
These deprecating or pre-warnings will be repeated in each release note version until the item has been changed or removed.
The corresponding documentation page will be updated with a deprecation or pre-warning message to highlight the upcoming change.
There will be a delay of at least 12 weeks between notification of the upcoming change and it being applied.
Once the item has been removed, a Removal release note entry will be provided indicating the removal, impact, and alternatives (if available).
We follow a version numbering convention that is similar to that
recommended by Semantic
Versioning. Basically, we use the
MAJOR.MINOR.PATCH numbering format,
which is defined as follows:
MAJOR: When there are major changes to the software, including high-profile ones, we'll change the value of this number, the primary number (e.g., the version will change from
MINOR: When we've added some new features or new functionality to LogScale software, we'll issue a new release and the secondary number will be changed (e.g.,
1.18). Unlike Semantic Versioning, though, we allow backwards incompatible changes (e.g., changing compression algorithms).
PATCH: When a patch is added, the tertiary or third number will be increased (e.g.,
1.18.1). Only backwards-compatible security or bug fixes are made with these. No new features or other code changes are permitted. This is important, as it means that each patch release should be more stable than the last.
Preview & Stable Releases
LogScale provides two separate releases:
Preview — includes new functionality that is still considered to be under development. Using a preview release gets you access to the newest features and functionality.
Preview releases get deployed every seven days on Community Edition, and the same release is deployed to US and EU Cloud customers the week after.
Stable — contains the latest functionality and is considered appropriate for production use.
LogScale on-premise customers are usually installing LogScale stable versions. These "on-prem" releases are provided at a slower pace than Cloud (preview) releases.
We aim to make a Stable (on-prem) release once every six weeks that contains a roll-up of all preview features.
Release Summary, Support, and Upgrade Requirements
When reviewing the release notes, a section at the top of each release notes sections provides basic information about the release and upgrade compatibility. For example:
|End of Support
Version— The full version number for this release.
Type— The release type, either Stable or Preview.
Release Date— The date when this version was released.
End of Support— The date when LogScale Support will no longer support this version.
Upgrades From— The minimum version of LogScale required to upgrade to this version. Upgrades from earlier versions may not succeed and are not recommended.
JDK Compatibility— The compatible JDK version required to upgrade to this version.
Data Migration— If No, you can safely upgrade without worrying about migrating your data. If Yes you will have to migrate data. This will be in relation to the last stable version, not the minimum previous version. See Updating LogScale for more information on how to do this.
Configuration Changes— Indicates whether there are configuration changes within the release that should be checked and updated during the upgrade process to ensure that they meet your requirements. See the Full Release Notes Index for information on the specific changes.
Built-in Release Information
To determine the version of LogScale you are using and view information on the latest releases available from the LogScale user interface:
Click the caption icon at the top of the screen: the Releases panel shows the full list of releases, with the most recent on top.
Click any release link for all detailed information on that release.
Figure 1. Built-in Release Information
If you're using LogScale Cloud, the latest — Preview or Stable — is used; upgrades are handled automatically for you.
Validating Release Checksums
The release notes include the checksum for release packages and docker images. You can verify the checksum for a package on the command-line.
To check an MD5 hash use the md5 tool:
$ md5 server-1.82.0.tar
MD5 (server-1.82.0.jar) = 4b4b4411d930d00275bc3a412c0c5c50
To check an SHA hash, use the shasum command:
$ shasum server-1.82.0.tar
To check an SHA256 hash, use the shasum command:
$ shasum -a 256 server-1.82.0.tar
To check an SHA512 hash, use the shasum command:
$ shasum -a 512 server-1.82.0.tar
If the checksums do not match the quoted values, you should obtain a new version of the package.