FPM
Docs
fpm User Manual
Development
Themes
Roadmap
Journal
How Versioning Works
How Versioning Works
FPM uses fallback based file tracking technique to implement versioning.
Versioning Happens At Project Level

Currently a package will either implement versioning or it will not.

If a project implements versioning, the top level of the project there would be version folders.

Normal layout looks like this:

Project Without Versioning
- package-folder
  - FPM.ftd
  - index.ftd
  - foo.ftd
For a project with versioning enabled:
Project With Versioning (foo.com package’s content)
- package-folder
  - FPM.ftd
  - v1/
    - index.ftd
    - foo.ftd
  - v2/
    - index.ftd
Notice that foo.ftd does not exist in v2 folder, since it has not been edited in v2.
Versioning Configuration
For files in FPM folder also we will do versioning, and we will have FPM/v1/config.ftd, FPM/v2/config and so on (a version would be present only if it’s actually edited in that version).
Versioning FPM.ftd
No FPM versioning. All versions will use same dependencies etc.
Deleting Files

Since we implement fallback based organization, if a file is not found a version folder, we search for the file in earler versions. If a file is supposed to be marked as deleted in some version, a file named <foo.ftd>.deleted should be created in that folder.

If in a future version the file is revived, the broken chain is considered logically the same file, so in dropdown we will show them.

Package URLs
If foo.com implements versioning, and have content as shown above, we will have URLs for each version, eg foo.com/v1/ (corresponding to index.ftd), foo.com/v1/foo/, foo.com/v2/andfoo.com/v2/foo/(even though there is nofoo.ftdinv2` folder).
Top level URLs

Further the latest version’s content would be reflected on top level, so we have foo.com/ and foo.com/foo/.

Top level URLs would use latest version as the canonical URL. NOT SURE ABOUT IT.

base URL

All urls in markdown etc should use only be partial urls, so eg if index.ftd is talking about foo.com/foo/ it should link to it using foo/.

If the project was foo.com/bar, the base URL is /bar/, and full URLs of the files mentioned above would be foo.com/bar/v1/, foo.com/bar/v1/foo/ and so on, so when linking we index.ftd will continue to use foo/ as path, and base URL would be set to /bar/v1/ etc, based on which file being built.

Version Dropdown
Version dropdown will show all versions. Latest version would be linked against the version number, eg foo.com/v2/ not foo.com/ even though the two have same content.
FPM Variables
To assist themes with versioning we have the following fpm variables:
boolean fpm.versioned: false
If this project is versioned or not.
optional string fpm.current-version
The current version.
ftd.toc-item list fpm.versions
All version prefixes, eg v1, v2, and so on. The link will point to the current document’s URL in that version. If the current document is not present in that version the link is not set.
boolean fpm.modified-in-current-version
If the file was modified in current version.
optional string fpm.previous-version
Where this document was edited. Eg v1.
optional string fpm.current-version-diff
The change in this version compared to the previous version.
optional string fpm.version-last-synced-on
When the current version was last synced with the previous version.
optional string fpm.previous-version-edited-on
option string fpm.version-last-diff
Diff in earlier version (where this file exists).
fpm version-status
This command will show all versions, and for each version the files that are out of date.
fpm mark-upto-date <v-new> <v-old>
Assets Versioning
Assets would not be versioned.
Versioned Dependencies
If a versioned package is used as a dependency, other packages can refer to things by paths defined in “Package URLs” section.
Translation And Versioning
If a versioned package is translated, translation packages can not change the logical structure. Meaning if a file v2/foo.ftd does not exist in English / Original package, it can not exist in Hindi / Translation package.
Version Status Page

In /-/version-status/ we will show all versions, and files in each version, which files are fallback and which are edited in specific version.

Further we will show all files that are out of date compared to changes in previous version of that file.