*This article has been updated to reflect the most current policy.
A key feature of the Brightspace Data Sets is a strong data contract – ensuring that the data we deliver works consistently and changes predictably. To facilitate this, we've developed a change management policy that outlines how to make changes in a way that adds value while protecting that important data contract. This policy maps to the Continuous Delivery Change Management rubric that can be found [BROKEN LINK]here. The policy outlines a version numbering scheme, which is used to communicate and control release of all changes.
Types of Change
Changes to the data sets fall into two categories – Minor Changes and Major Changes.
|
BDS Change Categories
|
CD Change Management
|
Enablement
|
Comments
|
|
Minor
|
None
|
Automatically enabled with no opt-out.
|
Notice provided in preview release notes with details in release notes with GA.
|
|
Slight
|
|
Moderate
|
Notice provided 90-days in advance.
|
|
Major
|
Large
|
Opportunity to opt-in for 6 months before automatically enabled with no opt-out.
|
Notice provided 90-days in advance with 6-month transition period.
|
|
Severe
|
Minor Change
These changes trigger an increment of a minor version number – for example, from version 1.9 to 1.10. It is recommended to develop around these types of changes so that code changes are not required.
Examples of Minor Changes:
|
Change
|
Hypothetical Example
|
Impact
|
Assumptions
|
CD Disruption
|
|
Adding data set
|
Intelligent Agents data set added
|
New data set appears in UI & API
|
Integrations are designed to ignore new data sets listed in the Data Sets List API Route .
|
Slight
|
|
Appending column
|
Last Modified Date column added to the end of the Grade Objects data set.
|
New column appears in data set after existing data elements
|
Integrations are designed to ignore new data elements but proceed with other data elements.
See [BROKEN LINK] a code example that demonstrates one approach to implementing this behavior.
|
Moderate
|
|
Add a column to the composite primary key
|
Primary key of Quiz Questions data set updated to include additional columns – one existing in data set and one column added to data set
|
The combination of columns that functions as primary key changes to include one or more additional columns
|
Integrations may need to be updated to use new composite primary key, but integrations will continue to function using previous composite primary key
|
Slight
|
|
Remove a column from the composite primary key, but column remains in data set
|
Primary key of Quiz Questions data set updated to no longer require a column – removed column still exists in data set
|
The combination of columns that functions as primary key no longer requires one or more columns
|
Integrations will continue to function using previous composite primary key, but integrations may find more value using the new composite primary key.
|
Slight
|
|
Adding new data in the form of additional rows
|
Soft deletes added to existing data set.
|
Additional rows appear in data set. Depending on use they may need filtered out.
|
Integrations may need to be updated to handle the new rows or filter them out.
|
Moderate
|
|
Changing whether a column can be NULL
|
Updating a column that previously could not be null to nullable.
|
Expect NULL values in processing of the data set.
|
Integrations will continue to function when something that could be NULL in the past now has a value for every row. However, there may need to be an update to expect a NULL value where there couldn’t be one before.
|
Moderate
|
|
Updating a column that previously could be null to not nullable.
|
No longer need to expect NULL values when processing.
|
Slight
|
| Changing data type of a column | Change of a column data type from bit to int. | Previous data type no longer valid | Integrations may need to be updated to handle the new data type | Moderate |
Major Change
Major changes are disruptive in nature. These changes may trigger an increment of a major version number – for example, from version 1.4 to 2.0. Major version changes can be opted into upon release and are automatically adopted six months following the Brightspace monthly update in which they are introduced. Some major changes may occur without a new major version and these changes will also provide a six month adoption period.
Examples of Major Changes:
|
Change
|
Hypothetical Example
|
Impact
|
Assumptions
|
|
Removing a column
|
ObjectLookupId2 column removed from Calendar Events data set
|
Column no longer exists in data set
In cases where the column was part of the composite primary key, the combination of columns that functions as composite primary key no longer requires the column being removed
|
Integrations must be updated to no longer expect missing data element in the data set
|
|
Renaming a column
|
ObjectId renamed to QuizId
|
The column name previously used would no longer exist with a new name taking its place.
|
Integrations must be updated to update the name of the existing column.
|
|
Changing column name character(s) to upper/lower case
|
Changing HistoryID to HistoryId.
|
The column name previously used would no longer exist with a new name taking its place.
|
Automatically detecting columns in integrations is case sensitive and will need to be updated.
|
|
Removing a data set
|
Awards data set removed
|
Data set no longer available for download
Some data set removals may occur without a major version change.
|
Integrations must be updated to remove dependencies on removed data set
|
Exceptions for High Priority Defect Fixes
When a defect is found that results in the inability to continue using a data set or blocks normal use, it will be addressed in the next available release. All attempts to fix the defect without disruption will be considered. However, this fix may include actions classified as major change in the table above if no other options are available. If the impact of not adopting the fix is high, the major change may be enabled by default following the release. D2L will consult with usage data to understand which clients may be largely impacted and to communicate with them directly.
Criteria for New Data Sets
All new data sets are in a beta period for up to 6 months to allow for a validation period during which clients can raise issues regarding quality and clarity of use. The beta period and its details will be clearly communicated to clients in the release notes on the Community.
Release Scenarios
Minor changes are automatically adopted during the Brightspace monthly update in which they are introduced. Major changes are automatically adopted six months following the Brightspace monthly update in which they are introduced. This latency is intended to provide sufficient lead time to update integrations to cope with the change. Clients can opt to adopt the Major change at any time during the six-month waiting period by updating their Brightspace Data Sets active version. See the Analytics Administrator Guide for instructions” with [BROKEN LINK]this link.
Scenario A - Minor version release
A Minor version is released and automatically adopted.
Example: 1.3 is the current active version. When 1.4 is released, it becomes the active version and 1.3 is no longer available. There are no options to opt-out of new changes.
Scenario B - Major version release
A Major version is released, adoption occurs following a six-month waiting period in which you can opt in to the major version.
Example: 2.4 is the current active version. When 3.0 is released, it is available feature-toggled off. Once it has been in-life for six releases, the active version becomes 3.0 and 2.4 is no longer available.
Scenario C - Major version release with minor versions that follow
A Major version is released, any subsequently released Minor versions replace that toggled-off version throughout the six-month waiting period and continue to be added to the current Major version.
Example: 3.1 is the current active version, but 4.0 is released as feature-toggled off to allow six releases before adoption. Two months later, 4.1 is released and replaces 4.0 as the toggled-off version during the waiting period and 3.2 replaces 3.1. Two months after that, 4.2 is released and replaces 4.1 as the toggled-off version for the remainder of the waiting period and 3.3 replaces 3.1. Therefore, after the six-release waiting period has elapsed for 4.0, the active version becomes 4.2.
Please note there may be some cases where the minor change being released is not applicable to the current major and will therefore only be applied to the new Major and be communicated as such.
Scenario D - Major version release with another major version that follows
When adoption of a Major version occurs, any subsequently released Major version must wait until there is once again a single version in production before releasing. D2L will only support two active Brightspace Data Set versions at a time.
Example: 3.1 is the current active version, but 4.0 is released as feature-toggled off to allow six releases before adoption. The following month, 5.0 is released. Therefore, after the six-release waiting period has elapsed for 4.0, adoption is triggered for that Major version. The following month,5.0 can be released and begin its 6-month adoption period.
| Scenario | January | February | March | April | May | June | July | August |
| A | 1.3 Active | 1.4 Released as Active
1.3 Removed | | | | | | |
| B | 2.4 Active
3.0 Released as Off | 2.4 Active
3.0 Off | 2.4 Active
3.0 Off | 2.4 Active
3.0 Off | 2.4 Active
3.0 Off | 2.4 Active
3.0 Off | 3.0 Active
2.4 Removed | |
| C | 3.1 Active
4.0 Released as Off | 3.1 Active
4.0 Off | 3.2 Active
3.1 Removed
4.1 Released as Off
4.0 Removed | 3.2 Active
4.1 Off | 3.3 Active
3.2 Removed
4.2 Released as Off
4.1 Removed | 3.3 Active
4.2 Off | 4.2 Active | |
| D | 3.1 Active
4.0 Released as Off | 3.1 Active
4.0 Off
| 3.1 Active
4.0 Off
| 3.1 Active
4.0 Off
| 3.1 Active
4.0 Off
| 3.1 Active
4.0 Off
| 4.0 Active
3.1 Removed
5.0 Released as Off | 4.0 Active
5.0 Off |
Tell us what you think
We welcome your feedback on this change management policy and the Brightspace Data Sets in general. Please post questions & feedback in the [BROKEN LINK]Data Access topic in the Brightspace Community or share your feedback with your D2L account representative.