Skip to content
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

Update versioning policy. #1912

Merged
merged 2 commits into from
Oct 13, 2021
Merged

Update versioning policy. #1912

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d23671
Update versioning policy.
rosiel Oct 8, 2021
dda0ef5
Update versioning.md
rosiel Oct 13, 2021
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
42 changes: 19 additions & 23 deletions docs/technical-documentation/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,51 +1,47 @@
# Versioning Policy

Islandora 8 uses semantic versioning, except for Drupal modules/themes, which use Drupal Contrib versioning.
Islandora uses semantic versioning for all non-Legacy code in the [github.com/Islandora](https://github.com/Islandora) organization. This allows us to be compatible with Composer and with [Drupal contrib module release](https://www.drupal.org/node/1015226) policy.
rosiel marked this conversation as resolved.
Show resolved Hide resolved

## [Semantic Versioning](http://semver.org/)
## Semantic Versioning

**Major version** . **Minor version** . **Patch**
[Semantic Versioning](https://semver.org/) is a common versioning standard. Versions have the form **Major version** . **Minor version** . **Patch**

- **Major version**; Major changes, and breaks the API
- **Minor version**; New features, and does not break the API
- **Patch**; Bug fixes, and never breaks backward compatibility

Examples:
### Examples

* `1.2.3 => 1.2.4` - Just a bug fix, should be a drop-in replacement.
* `1.2.3 => 1.3.0` - Adds in new features, should be a drop-in replacement to get new functionality.
* `1.2.3 => 2.0.0` - Major changes, may require a migration or changes to your set-up.

The following Islandora 8 components use semantic versioning:
### Repositories under semantic versioning

The following Islandora components use semantic versioning:

* [Alpaca](https://github.com/Islandora/Alpaca)
* [Chullo](https://github.com/Islandora/Chullo)
* [Crayfish](https://github.com/Islandora/Crayfish)
* [Crayfish Commons](https://github.com/Islandora/Crayfish-Commons)
* [Syn](https://github.com/Islandora/Syn)
* [controlled\_access\_terms](https://github.com/Islandora/controlled_access_terms) (Drupal module)
* [islandora](https://github.com/Islandora/islandora/tree/8.x-1.x) (Drupal module)
* [islandora_defaults](https://github.com/Islandora/islandora_defaults) (Drupal module)
* [jsonld](https://github.com/Islandora/jsonld) (Drupal module)
* [openseadragon](https://github.com/Islandora/openseadragon) (Drupal module)

## [Drupal Contrib Versioning](https://www.drupal.org/docs/8/choosing-a-drupal-version/what-do-version-numbers-mean-on-contributed-modules-and-themes)

**Core Compatibility** - **Major** . **PatchLevel[-Extra]**
Drupal submodules, which are included in several of the above modules, share versions with their parents.

Examples:
!!! note "Drupal module versions switched from 8.x-1.x to 2.x"
In October 2021, Islandora switched from the "[core compatibility](https://www.drupal.org/docs/8/understanding-drupal-version-numbers/what-do-version-numbers-mean-on-contributed-modules-and)" based numbering scheme (8.x-1.x) to a pure semantic versioning scheme for its Drupal modules. In accordance with [Drupal's requirements](https://www.drupal.org/node/1015226#semver-transition), this transition required us to bump the major version, from 1.x to 2.x, despite there not being any major API-breaking changes to the code itself.

* `8.x-1.0 => 8.x-1.1` - Just a bug fix, should be a drop-in replacement.
* `8.x-1.0 => 8.x-2.0` - Major changes, could require a migration or changes to your set-up.
## Implications for Release Process

The `8.x-` part will not change to `9.x-` until Drupal 9.
Committers should now create (i.e. "tag") new versions of components when new bug fixes, features, or API changes are successfully added. This means that "releases" (new versions) will be happening individually, continually, and far more frequently than before. See [Releasing Islandora](../contributing/releasing-islandora.md).

The following Islandora 8 components use Drupal Contrib versioning:
## Module Interdependencies

* [carapace](https://github.com/Islandora/carapace)
* [controlled\_access\_terms](https://github.com/Islandora/controlled_access_terms)
* [drupal-project](https://github.com/Islandora/drupal-project)
* [islandora](https://github.com/Islandora/islandora/tree/8.x-1.x)
* [islandora_defaults](https://github.com/Islandora/islandora_defaults)
* [jsonld](https://github.com/Islandora/jsonld)
* [openseadragon](https://github.com/Islandora/openseadragon)
When Islandora components require other Islandora components in their `composer.json` files, we prefer the version specification syntax `^2` to point to the latest-released compatible version within the specified major version.

This list does *not* include sub-modules which share versions with their parents.

ie.
[Islandora Audio](https://github.com/Islandora/islandora/tree/8.x-1.x/modules/islandora_audio), [Islandora IIIF](https://github.com/Islandora/islandora/tree/8.x-1.x/modules/islandora_iiif) and [Islandora Breadcrumbs](https://github.com/Islandora/islandora/tree/8.x-1.x/modules/islandora_breadcrumbs) are all sub-modules of Islandora and shares its version.