Version changelog

2.0.0

Initial public release of quantum-version.

Added

Creates pipeline transformation functions for quantum-version. This function takes the config for configuring quantum version, and returns a function for transforming pages (a FileTransform ).

added

Added

Can be added to any content that should only be included in the page starting from a certain version.

For example, this function will only be included in pages with version 2.1.0 or later:

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @added 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionadded

Added

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

removed

Added

Can be added to any content that should stop being included in the page after a certain version. The content will remain in the page for the version specified, but any versions later than the one given will not include the content.

For example, this function will only be included in pages from versions 2.1.0 up to 3.0.0:

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @removed 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionremoved

Removed

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

deprecated

Added

This tag has no real affect on the content that is output, but when other modules are used, such as quantum-api, this tag can have an affect on the visible output - for quantum-api a notice is displayed in the api section.

Normally a deprecated tag will sit before a @removed tag.

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @deprecated 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctiondeprecated

Deprecated

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

updated

Added

This tag has no real affect on the content that is output, but when other modules are used, such as quantum-api, this tag can have an affect on the visible output. A notice will be displayed for just the version specified. The content for the notice will be taken from the @description tag.

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @updated 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionupdated

Updated

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

versionedPage

Added

This marks a page as "versioned", which means that it will be processed by the version fileTransform. Any pages without this entity will pass through the version file transform untouched.

The list of versions for this page can be included in this entity. An alternative way of doing this is to set the list of entities in the options passed into version.fileTransform() in the quantum.config.json.

Example: when the versions are set in quantum.config.json

@versionedPage

Example: specifying the versions in the page itself

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 1.2.0
  @version 1.2.1
  @version 1.3.0
  @version 2.0.0

Example: Using inlining

index.um

@versionedPage
  @inline ./versions.um

versions.um

@version 1.0.0
@version 1.1.0
@version 1.2.0
@version 1.2.1
@version 1.3.0
@version 2.0.0

versioned

Added

Versioned content provides alternative versions of content for different versions. It does a full replacement for each version. Content remains the same between versions.

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versioned
  @version 1.0.0: Description 1
  @version 2.0.0: Description 2

The output will be (3 separate files)

1.0.0/index.um

Description 1

1.1.0/index.um

Description 1

2.0.0/index.um

Description 2

versionList

Added

An entity that will be populated with the full list of versions and the current version when the file is processed by the version page transform.

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versionList

The output will be (3 separate files)

1.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.0.0

1.1.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.1.0

2.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 2.0.0

processTagsentityEntityversionStringversionsArray[String]fileFile

Added

Processes all the tags in the content passed in. This involves only keeping content that satisfy the @added and @removed tags for the version specified.

The @updated and @deprecated tags are removed if they do not apply to the version passed in.

processVersionedentityEntityversionStringversionsArray[String]

Added

Processes the @versioned sections in the entity passed in. This removes all @versioned sections from the entity (recursively) and replaces then with the correct content for the version given.

Example

const version = require('quantum-version')

const entity = {
  params: [],
  content: [
    {
      type: 'versioned',
      params: [],
      content: [
        {
          type: 'version',
          params: ['0.1.0'],
          content: [
            "Content1"
]
},
{
  type: 'version',
  params: ['0.3.0'],
  content: [
    "Content2"
]
}
]
}
]
}

const versions = ['0.1.0', '0.2.0', '0.3.0']

version.processVersioned(entity, '0.1.0', versions)
console.log(entity)
// { params: [], content: ['Content1'] }

version.processVersioned(entity, '0.2.0', versions)
console.log(entity)
// { params: [], content: ['Content1'] }

version.processVersioned(entity, '0.3.0', versions)
console.log(entity)
// { params: [], content: ['Content2'] }

processVersionListsentityEntitycurrentVersionStringversionsArray[String]

Added

Looks for all the @versionList entities in the entity passed in (recursively), and populates them with the full list of versions for the page, as well as the current version.

This function handles the following functionality:

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versionList

The output will be (3 separate files)

1.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.0.0

1.1.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.1.0

2.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 2.0.0

1.0.0

Version 1.0.0 is an unsupported version of the library.