How sync/CR works

FPM.ftd

@@ -55,6 +55,9 @@ implements: fifthtry.github.io/theme
   - `fpm diff`: /diff/
   - `fpm update`: /update/
   - `fpm serve`: /serve/
+  - `fpm add`: /cli/add/
+  - `fpm rm`: /cli/rm/
+  - `fpm edit`: /cli/edit/
 
 
 

cli/add.ftd

@@ -0,0 +1,29 @@
+-- ft.page: `fpm add <file-name>`
+
+
+This would create entry in workspace.ftd and only the files added would be
+consider for sync.
+
+-- ft.h1: `fpm add -/<cr-number>/<file-name>`
+
+This command should check that a file in cr `-/<cr-number>/<file-name>` exists.
+
+-- ft.code: `.client-workspace/workspace.ftd`
+lang: ftd
+
+\-- fpm.client-workspace: <file-name>
+cr: <cr-number>
+
+
+-- ft.h1:  Error handling
+
+Adding a file that exists in latest history would suggest to use `fpm edit`
+instead.
+
+
+
+
+
+
+
+

cli/edit.ftd

@@ -0,0 +1,32 @@
+-- ft.page: `fpm edit <file-name> --cr <cr-number>`
+
+This command works with cr number only, else it fails
+This would create entry in workspace.ftd and only the files added would be
+consider for sync.
+
+This command will copy the file in cr directory `-/<cr-number>` and also
+start tracking with the latest version.
+
+
+-- ft.code: `.client-workspace/workspace.ftd`
+lang: ftd
+
+\-- fpm.client-workspace: -/<cr-number>/<file-name>
+version: <remote-version>
+
+
+-- ft.code: `.tracks/-/<cr-number>/<file-name>`
+lang: ftd
+
+\-- fpm.tracks: <file-name>
+version: <remote-version>
+
+
+-- ft.h1:  Error handling
+
+If file is already in `-/<cr-number>` directory, throw error
+If the file doesn't exist in the latest history then throw error
+
+
+
+

cli/rm.ftd

@@ -0,0 +1,42 @@
+-- ft.page: `fpm rm`
+
+
+-- ft.h1: `fpm rm <file-name>`
+
+This would mark the file deleted in workspace.ftd.
+This would delete the file.
+
+-- ft.code: `.client-workspace/workspace.ftd`
+lang: ftd
+
+\-- fpm.client-workspace: <file-name>
+version: <remote-version>
+cr: <cr-number>
+deleted: true
+
+-- ft.h1: `fpm rm <file-name> --cr <cr-number>`
+
+This would add an entry in -/<cr-number>/-/delete.ftd
+
+-- ft.code: `-/<cr-number>/-/delete.ftd`
+lang: ftd
+
+\-- fpm.deleted: <file-name>
+version: <remote-version>
+
+
+-- ft.code: `.client-workspace/workspace.ftd`
+lang: ftd
+
+\-- fpm.client-workspace: -/<cr-number>/-/delete.ftd
+version: <remote-version>
+cr: <cr-number>
+
+
+-- ft.h1: Error Handling
+
+If the file doesn't exist in the latest history then throw error
+
+
+
+

dev/cr.ftd

@@ -0,0 +1,188 @@
+-- ft.page: How CR Works
+
+-- ft.h1: Reserved CR IDs
+
+Each clone has a unique id, stored in `.client-state/clone-id.ftd`. The id is
+created by the server.
+
+On clone we create `.client-state/reserved-crs.ftd`, and store the 5 CR numbers
+we get from server.
+
+Server will have `.server-state/reserved-crs.ftd` which will mention the CRs
+handed out to each "clone".
+
+-- ft.code: `.server-state/reserved-crs.ftd`
+lang: ftd
+
+\-- client: <client-id>
+reserved-cr: 1
+reserved-cr: 2
+reserved-cr: 3
+reserved-cr: 4
+reserved-cr: 5
+
+\-- client: <client-id>
+reserved-cr: 6
+reserved-cr: 7
+reserved-cr: 8
+reserved-cr: 9
+reserved-cr: 10
+
+-- ft.markdown:
+
+On every sync, we replenish our reserved CR pool.
+
+-- ft.h1: Create A New CR
+
+`fpm create-cr "<title of CR>"` can be used to create a CR. 
+
+
+-- ft.markdown:
+
+We find the smallest CR number from reserved CR, and create
+`/-/<cr-id>/-/meta.ftd`:
+
+-- ft.code:
+lang: ftd
+
+\-- import: fpm
+
+\-- fpm.cr: <title>
+status: open
+
+-- ft.markdown:
+
+On next `fpm sync`, the `meta.ftd` file would be synced and everyone will have
+access to it. Server will also replenish the reserved cr pool as we have
+consumed one CR number from there.
+
+-- ft.h1: Edit CR Description
+
+The description of a CR is stored in `/-/<cr-id>/-/about.ftd`.
+
+`fpm cr <cr-number> edit` launched `$EDITOR` with the content of `about.ftd`.
+
+If the file does not exist it will be initialised with `FPM/default-cr-about.ftd` if
+present, else, `THEME/default-cr-about.ftd`.
+
+
+-- ft.h1: Edit CR Title
+
+`fpm cr <cr-number> edit-title` will launch `$EDITOR` with current title.
+
+Note: Only the first line would be used as CR title. Content before the first
+new line character is first line.
+
+
+
+-- ft.h1: Add a new file in CR
+
+`fpm cr <cr-number> --add <filename>`
+
+To add a new file, create the file `/-/<cr-id>/<file.ftd>`, and let user edit
+the file.
+
+On sync the file would be synced. From sync's perspective this is just a normal
+file. Before sync `workspace.ftd` will not have a version number for this file,
+and post sync it will.
+
+-- ft.h1: Edit an existing file in CR
+
+`fpm cr <cr-number> --add <filename>`
+
+If we want to edit `foo.ftd` in CR 1, we have to create `-/1/foo.ftd` and make
+it [start tracking](/dev/track/) `foo.ftd`.
+
+On the sync the two files will be synced with server. One every update server
+will update the `self-version` in the `.track/-/1/foo.ftd`.
+
+-- ft.h1: Editing a file both on client and server
+
+Say you started editing the file, but someone else also started editing the
+file at the same time and their sync landed first. If we handle this as regular
+conflict (both sides added a file) we ask end users to do a lot. We can make
+users life better by implementing a special case for this scenario, and use the
+smaller version number from both tracking files, and do a three way sync. If the
+sync succeeds there is no conflict.
+
+-- ft.h1: Delete a file in CR
+
+`fpm rm <filename> --cr <cr-number>`
+
+We will have a file called `/-/1/-/deleted.ftd` which stores all the files and
+their versions that were deleted by CR number 1.
+
+-- ft.code:
+lang: ftd
+
+\-- fpm.deleted: file/name.ftd
+version: v1
+
+-- ft.markdown:
+
+This file gets synced with server as normal file.
+
+-- ft.h1: Detect conflict in CR
+
+We can detect if a file `/-/1/foo.ftd` in CR 1 is conflicted with corresponding
+`foo.ftd` in main by looking at `.track/-/1/foo.ftd.track` to get the version
+number, and finding the content of that version of `foo.ftd` from
+`.server-state/foo.<version>.ftd`, and using it as "base", and content of
+`foo.ftd` as "theirs" and content of `/-/1/foo.ftd` as ours and do three way
+merge.
+
+If `/-/1/foo.ftd` does not exist, we check for `/-/1/-/deleted.ftd`, and see if
+the version for `foo.ftd` in that file is different than the latest version of
+`foo.ftd`.
+
+-- ft.h1: Merge changes in main to CR
+
+`fpm merge --src=main --dest=1 foo.ftd` # --src=main is default, if no
+file/folder name, merge all
+
+
+Merge only happens on server for now
+
+We perform the three way merge as described in  previous section. We use content
+of `foo.ftd` as "theirs" and content of `/-/1/foo.ftd` as "ours". If there is
+no conflict we update `/-/1/foo.ftd` with the merged content, and update the
+tracking information corresponding to `/-/1/foo.ftd` against `foo.ftd` (store
+the version of `foo.ftd` we just merged in `.track/-/1/foo.ftd`.
+
+-- ft.h1: Merge CR changes to main
+
+
+`fpm merge --src=1 --dest=main foo.ftd`
+
+Merge only happens on server for now
+
+We perform the three way merge as described in previous section. We use content
+of `foo.ftd` as "ours" and content of `/-/1/foo.ftd` as "theirs". If there is
+no conflict we update `foo.ftd` with the merged content, delete `/-/1/foo.ftd`,
+and `.track/-/1/foo.ftd` and increment the version number of all three files in
+`history.ftd`.
+
+-- ft.h1: Resolve conflict in CR when merging from main Or from CR into main
+
+In both these scenarios, we will create a temporary file with conflict markers
+as described in previous two steps and launch `$EDITOR`, and once user has
+resolved conflict we will do what is described in previous two steps.
+
+-- ft.h1: Close a CR
+
+To close a CR we update the `about.ftd` and set `status: closed`.
+
+`fpm close-cr <cr-number>`
+
+This sets the `close` flag in `-/<cr-number>/-/about.ftd`.
+
+
+-- ft.h1: Update CR About
+
+
+-- ft.h1: `fpm status --cr=1`
+-- ft.h1: `fpm status` (sync status)
+-- ft.h1: `fpm status --versions`
+-- ft.h1: `fpm status --translation`
+
+