new feature: versioning

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

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 `<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.
+
+
+-- 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 <v-new> <v-old>`
+
+
+-- 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.