Skip to content

Add more details to upgrade docs #318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 26, 2025
Merged

Add more details to upgrade docs #318

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b211569
Add more details to upgrade docs
pmonks Apr 25, 2025
d85b02b
Add more details to upgrade docs
pmonks Apr 26, 2025
0753b01
Add more details to upgrade docs
pmonks Apr 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions README-V3-UPGRADE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ With the support of SPDX 3.0, several changes have been made to the library code
Although we tried to keep breaking changes to a minimum, some of the changes were necessary due to breaking changes in the spec. itself.
We also took advantage of the changes to fix some annoying design flaws in the previous implementation of the library.

## New initialisation methods

v2 of the library introduces an explicit initialisation process. This involves:

1. (optional) Calling `org.spdx.core.DefaultModelStore.initialize(...)` with your own choice of ModelStore and CopyManager.
2. (required) Calling `org.spdx.library.SpdxModelFactory.init()` (this must happen _soon after_ the call to `DefaultModelStore.initialize()` - ideally before any other SPDX classes or methods are used).

Notes:

- Step #1 is optional; if not provided, a default ModelStore and CopyManager will be automatically created and configured by `SpdxModelFactory.init()`.
- Once initialized (via Step #2), further calls to `DefaultModelStore.initialize(...)` will be ignored.

## Classes and Methods moved to SPDX Java Core library

The SPDX Java Core Library is in a separate repository and jar file.
Expand All @@ -21,6 +33,14 @@ The packages in `org.spdx.licenseTemplates` are now in the `java-spdx-core` repo

A new class `LicenseTextHelper` was added and the method `isLicenseTextEquivalent(String, String)` along with many supporting methods were moved to `LicenseTextHelper` from `org.spdx.utility.compare.LicenseCompareHelper`.

## Other moved classes

- `org.spdx.library.model.license.ListedLicenses` moved to `org.spdx.library.ListedLicenses`

## Removed methods

Some methods that exist in the v2.3 model classes (e.g. `org.spdx.library.model.license.SpdxListedLicense.getLicenseTextHtml()`, `org.spdx.library.model.license.SpdxListedLicense.getCrossRef()`, `org.spdx.library.model.license.ListedLicenseException.getExceptionTextHtml()`) have been removed and do not have an equivalent in the v3.0 model classes.
Copy link
Collaborator Author

@pmonks pmonks Apr 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@goneall please confirm that this is true. I couldn't find where these methods went, but I'm not 100% sure they don't in fact exist somewhere in one of the other new libraries.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is true - the SPDX 3 specification does not define these three fields.

A bit of background - the 3 fields were added to the SPDX 2 model to enable the license list publisher to use the standard model for publishing. The 3 fields never made it into the spec, however. In hindsight, we probably should have created a subclass of listed license to store the additional fields - but I don't want to implement something that may break compatibility.

@zvr @swinslow - do you see any value of adding the information used to generate the license website to the actual listed license model? If so, we can propose adding them back to the SPDX 3 model.


## Changes to SPDX version 2 package, class, and method names

To support accessing SPDX 2.X model object while updating the library for SPDX 3.0 support, the package names for the SPDX 2.X model objects are now named `org.spdx.library.model.v2.[package]`.
Expand All @@ -29,6 +49,10 @@ Many of the class and property names have been changed to append `CompatV2` to c

Also note that the model classes are now stored in a separate repository `spdx-java-model-2_X`.

## SPDX version 3.x package

SPDX 3.0.1 model objects can be found in packages underneath `org.spdx.library.model.v3_0_1`. Note that Spdx-Java-Library will only track the latest minor+patch version for the last 2 major SPDX specification versions (i.e. v2.3.0 and v3.0.1), because minor+patch versions of the SPDX specification are backwards compatible _within_ a major version.

## Changes to ExternalElement and ExternalExtractedLicenseInfo (SPDX Version 2.X classes)

- Constructors changed to take the document URI for the document containing the external element or license. This is different from the previous constructor which took the document URI of the document containing the reference and an ID of the form `DocumentRef-XX:[ID]` To accomodate compatibility, the constructors
Expand Down