From 91ec830eb6c6b137e31353f88e7ab4072a631d43 Mon Sep 17 00:00:00 2001 From: Arpita-Jaiswal Date: Wed, 20 Apr 2022 13:43:30 +0530 Subject: [PATCH 1/3] Doc for fpm PR#160 --- FPM/config.ftd | 1 + crate/deps/fbt.ftd | 11 +++++++++++ crate/deps/ftd.ftd | 3 +++ 3 files changed, 15 insertions(+) create mode 100644 crate/deps/fbt.ftd diff --git a/FPM/config.ftd b/FPM/config.ftd index be7bb7058..9109f9f21 100644 --- a/FPM/config.ftd +++ b/FPM/config.ftd @@ -90,6 +90,7 @@ $processor$: toc url: crate/utils/ - Dependencies - `ftd`: crate/deps/ftd/ + - `fbt-lib`: crate/deps/fbt/ - `camino`: crate/deps/camino/ diff --git a/crate/deps/fbt.ftd b/crate/deps/fbt.ftd new file mode 100644 index 000000000..98511fc61 --- /dev/null +++ b/crate/deps/fbt.ftd @@ -0,0 +1,11 @@ +-- ft.page-with-toc: Dependency: `fbt-lib` +toc: $config.crate-toc +sub-sections: $config.dev-section +extra: $config.empty + + +We use [`fbt-lib`](https://docs.rs/fbt-lib/) in development mode for testing. +Tests are present in [test folder](https://github.com/FifthTry/fpm/tree/main/tests). + +Version: [0.1.18](https://crates.io/crates/fbt-lib/0.1.18) + diff --git a/crate/deps/ftd.ftd b/crate/deps/ftd.ftd index d7e7dbc6b..1b18042fb 100644 --- a/crate/deps/ftd.ftd +++ b/crate/deps/ftd.ftd @@ -6,3 +6,6 @@ extra: $config.empty We use [`ftd`](https://docs.rs/ftd/) crate which handles ftd grammer and compilation of ftd files in HTML etc. + +Version: [git-c317e24](https://github.com/FifthTry/ftd/commit/c317e24e948a6e8e8d83c75a9789f27453d41fcf) + From f2622ce7ba574f54f102392061c5e32ed31e7697 Mon Sep 17 00:00:00 2001 From: Arpita-Jaiswal Date: Wed, 20 Apr 2022 14:10:14 +0530 Subject: [PATCH 2/3] Added How To Run Tests and How To Update Failing Snapshot Tests in day to day secrtion --- FPM/config.ftd | 5 ++- crate/deps/{fbt.ftd => fbt-lib.ftd} | 2 +- day-to-day/how-to-fix-tests.ftd | 20 ++++++++++ day-to-day/how-to-run-tests.ftd | 57 +++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 2 deletions(-) rename crate/deps/{fbt.ftd => fbt-lib.ftd} (75%) create mode 100644 day-to-day/how-to-fix-tests.ftd create mode 100644 day-to-day/how-to-run-tests.ftd diff --git a/FPM/config.ftd b/FPM/config.ftd index 9109f9f21..8ae5cd3a9 100644 --- a/FPM/config.ftd +++ b/FPM/config.ftd @@ -88,9 +88,12 @@ $processor$: toc - Private Stuff - `fpm::utils` url: crate/utils/ +- Day To Day + - How To Run Tests: day-to-day/how-to-run-tests/ + - How To Update Failing Snapshot Tests: day-to-day/how-to-fix-tests/ - Dependencies - `ftd`: crate/deps/ftd/ - - `fbt-lib`: crate/deps/fbt/ + - `fbt-lib`: crate/deps/fbt-lib/ - `camino`: crate/deps/camino/ diff --git a/crate/deps/fbt.ftd b/crate/deps/fbt-lib.ftd similarity index 75% rename from crate/deps/fbt.ftd rename to crate/deps/fbt-lib.ftd index 98511fc61..d3ab5ad1c 100644 --- a/crate/deps/fbt.ftd +++ b/crate/deps/fbt-lib.ftd @@ -5,7 +5,7 @@ extra: $config.empty We use [`fbt-lib`](https://docs.rs/fbt-lib/) in development mode for testing. -Tests are present in [test folder](https://github.com/FifthTry/fpm/tree/main/tests). +Tests are present in [tests folder](https://github.com/FifthTry/fpm/tree/main/tests). Version: [0.1.18](https://crates.io/crates/fbt-lib/0.1.18) diff --git a/day-to-day/how-to-fix-tests.ftd b/day-to-day/how-to-fix-tests.ftd new file mode 100644 index 000000000..4d4e11e0a --- /dev/null +++ b/day-to-day/how-to-fix-tests.ftd @@ -0,0 +1,20 @@ +-- ft.page-with-toc: How To Update Failing Snapshot Tests +toc: $config.crate-toc +sub-sections: $config.dev-section +extra: $config.empty + +We can fix the failing tests which is due to snapshot mismatch in output folder. + +-- ft.code: +lang: sh + +fbt --fix + +-- ft.markdown: + +This will update the snapshots of all the tests + +Prerequisite: Read this [How To Run Tests](day-to-day/how-to-run-tests/) + + + diff --git a/day-to-day/how-to-run-tests.ftd b/day-to-day/how-to-run-tests.ftd new file mode 100644 index 000000000..e85495aca --- /dev/null +++ b/day-to-day/how-to-run-tests.ftd @@ -0,0 +1,57 @@ +-- ft.page-with-toc: How To Run Tests +toc: $config.crate-toc +sub-sections: $config.dev-section +extra: $config.empty + + +Steps: + +In the terminal, run the following commands + +-- ft.code: +lang: sh + +cargo install fbt + + +-- ft.markdown: + +This will install the latest [fbt](https://crates.io/crates/fbt) + +-- ft.code: +lang: sh + +fbt + +-- ft.markdown: + +This will run all the tests present in [tests folder](https://github.com/FifthTry/fpm/tree/main/tests). + +The output will look somewhat like this + +``` +01-help: PASSED in 1.94192775s +02-hello: PASSED in 2.064883375s +03-nested-document: PASSED in 986.959958ms +04-import-package-doc: PASSED in 897.559292ms +05-fpm-dependency: SKIPPED (dependency seems to be broken during refactor) +06-hello-font: SKIPPED (package-info not yet fixed) +07-nested-document-sync: PASSED in 1.055493916s +08-hello-tracks: PASSED in 1.65271375s +09-static-assets: SKIPPED (package-info not yet fixed) +10-markdown-pages: SKIPPED (temporarily removed markdown support) +11-readme-index: SKIPPED (temporarily removed markdown support) +12-readme-with-index: SKIPPED (temporarily removed markdown support) +13-translation: SKIPPED (package-info not yet fixed) +14-translation-hindi: SKIPPED (package-info not yet fixed) +15-recursive-download-dependencies: PASSED in 812.663917ms +16-translation-mark-upto-date-and-translation-status: PASSED in 745.278333ms +17-fpm-dependency-alias: PASSED in 947.086041ms +18-include-processor: PASSED in 3.253793333s +19-dependency-alias-prelude: PASSED in 1.598941708s +``` + +Next: Read this [How To Update Failing Snapshot Tests](day-to-day/how-to-fix-tests/) + + + From eba41e3d2bf00453ee7353aac05375be2a608139 Mon Sep 17 00:00:00 2001 From: Arpita-Jaiswal Date: Thu, 21 Apr 2022 15:24:47 +0530 Subject: [PATCH 3/3] Initial commit --- FPM/config.ftd | 5 ++- dev/versioning.ftd | 105 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 2 deletions(-) create mode 100644 dev/versioning.ftd diff --git a/FPM/config.ftd b/FPM/config.ftd index 8ae5cd3a9..83914fad5 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 diff --git a/dev/versioning.ftd b/dev/versioning.ftd new file mode 100644 index 000000000..37f27027a --- /dev/null +++ b/dev/versioning.ftd @@ -0,0 +1,105 @@ +-- 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: `fpm.package` + +`fpm.package` includes one more field `versioned` of boolean type with +default value as false. Set this field to true to enable versioning. + +-- ft.code: +lang: ftd + +-- fpm.package: +versioned: true + + + +-- ft.h2: Versioning FPM.ftd + +No FPM versioning. All versions will use same dependencies etc. + + +-- 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: `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. +