diff --git a/FPM/config.ftd b/FPM/config.ftd index be7bb7058..620d54573 100644 --- a/FPM/config.ftd +++ b/FPM/config.ftd @@ -60,8 +60,9 @@ $processor$: toc -- fpm.toc-item list dev-toc: $processor$: toc -- Roadmap: /roadmap/ -- Journal: /journal/ +- Roadmap: roadmap/ +- Journal: journal/ +- How Versioning Works: dev/versioning/ -- fpm.toc-item list crate-toc: $processor$: toc @@ -135,14 +136,4 @@ $processor$: toc - Installation: /about/ -/-- ft.footer-toc: Learn -children: $learn -/-- ft.footer-toc: Community -children: $community - -/-- ft.footer-toc: More -children: $more - -/-- ft.footer-toc: Legal -children: $legal diff --git a/dev/versioning.ftd b/dev/versioning.ftd new file mode 100644 index 000000000..45122f105 --- /dev/null +++ b/dev/versioning.ftd @@ -0,0 +1,168 @@ +-- ft.page-with-toc: How Versioning Works +toc: $config.dev-toc + +FPM uses fallback based file tracking technique to implement versioning. + +-- ft.h1: 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: + +-- ft.code: Project Without Versioning +lang: txt + +- package-folder + - FPM.ftd + - index.ftd + - foo.ftd + +-- ft.markdown: + +For a project with versioning enabled: + +-- ft.code: Project With Versioning (foo.com package's content) +lang: txt + +- package-folder + - FPM.ftd + - v1/ + - index.ftd + - foo.ftd + - v2/ + - index.ftd + +-- ft.markdown: + +Notice that `foo.ftd` does not exist in `v2` folder, since it has not been +edited in v2. + + +-- ft.h2: 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). + +-- ft.h2: Versioning FPM.ftd + +No FPM versioning. All versions will use same dependencies etc. + + +-- ft.h2: 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 `.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. + + +-- ft.h1: 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/` and `foo.com/v2/foo/` (even though there is no +`foo.ftd` in `v2` folder). + +-- ft.h2: 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. + + +-- ft.h1: `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. + + +-- ft.h1: 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. + + +-- ft.h1: FPM Variables + +To assist themes with versioning we have the following fpm variables: + +-- ft.h2: `boolean fpm.versioned: false` + +If this project is versioned or not. + +-- ft.h2: `optional string fpm.current-version` + +The current version. + +-- ft.h2: `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. + +-- ft.h2: `boolean fpm.modified-in-current-version` + +If the file was modified in current version. + +-- ft.h2: `optional string fpm.previous-version` + +Where this document was edited. Eg `v1`. + +-- ft.h2: `optional string fpm.current-version-diff` + +The change in this version compared to the previous version. + +-- ft.h2: `optional string fpm.version-last-synced-on` + +When the current version was last synced with the previous version. + +-- ft.h2: `optional string fpm.previous-version-edited-on` + +-- ft.h2: `option string fpm.version-last-diff` + +Diff in earlier version (where this file exists). + +-- ft.h2: `fpm version-status` + +This command will show all versions, and for each version the files that are +out of date. + +-- ft.h2: `fpm mark-upto-date ` + + +-- ft.h1: Assets Versioning + +Assets would not be versioned. + +-- ft.h1: Versioned Dependencies + +If a versioned package is used as a dependency, other packages can refer to +things by paths defined in "Package URLs" section. + +-- ft.h1: 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. + +-- ft.h1: 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.