Built-in way to synchronize with github's foam-template?

[cmcconomy-element]

I think it would be useful to be able to merge in changes from foam-template (as once you've cloned, you lose the ability to pull subsequent changes).

Having done a bit of research, some interesting work appears to have been pursued here, which would permit a 'github action' to run the merge: https://github.com/narrowspark/template-sync-action

However, it appears to be broken right now and I'm not in a position to fix it. If someone reading this has the inclination they could look at this as a solution. By changing the launch type from cron to workflow_dispatch, it can be launched with a button from the cloned github repo's "action" page, which would be quite unobtrusive.

[riccardoferretti]

Thanks for the pointer @cmcconomy-element, I agree this would be great to have. At some point we might even build this into Foam, would love to get comments on how to approach this functionality in one way or another.

[cmcconomy-element]

Thanks for the pointer @cmcconomy-element, I agree this would be great to have. At some point we might even build this into Foam, would love to get comments on how to approach this functionality in one way or another.

Maybe take another half-step back and ask why we are recommending a 'template' instead of a 'fork'. I believe the intention of templates is a one-time starter whereas forks are more of a 'conversation' with the upstream repo.

There is a risk to fork semantics - pulling a merge might threaten to squash some of your config/documentation! In this case, the base project (fork/template) should carefully consider their structure so that further updates are unlikely to impact an active user, should they choose to pull in changes. For example, foam could institute a 'userdata' folder convention to which all user-written docs are isolated, protecting them from upstream changes in the 'intro' docs and other paraphernalia that comes with the foam template.

Finally, the instructions could offer advice to template or fork with a brief description of the benefits and drawbacks of each approach (ie, "get a copy of foam frozen in time at version x.y.z" vs "updatable foam instance, however see our 'updating foam' page for advice on safely pulling updates").

[SanketDG]

Maybe take another half-step back and ask why we are recommending a 'template' instead of a 'fork'. I believe the intention of templates is a one-time starter whereas forks are more of a 'conversation' with the upstream repo.

The problem is the idea of templates (and distributing them) makes more sense here because it makes publishing more accessible, opens up the ground for composition and mixing/matching things.

"Forks" on the other hand is just a git thing, although some of the principles are relevant.

I think what we are missing primarily is the ability to "incrementally compose" the settings.json (among other things)

This is also in general a problem of the scaffolding ecosystem.

[cmcconomy-element]

@SanketDG Makes sense, though this is more than publishing a web page or set of documents: it's a technical infrastructure. I like the concept of composable configs, maybe a defaults config file that we pull updates for and a user config file that overlays on top of it (stealing a page from sublimetext).

Another possibility is further separating the documents from the app by using a git submodule approach?

[riccardoferretti]

Yes those are all valid points, and good find on that document, interesting read.

My rough thinking around this was to use the .foam/ dir to separate as much as possible "user context" from "foam context". At the same time, even within .foam/ there are things that originate from the template, but can be overridden by the user. Configuration is one example, and what you wrote about composable configs makes perfect sense as possible approach to alleviate that problem.

Maybe another way to look at it is understanding what problem this is trying to solve, can you share some examples?

[cmcconomy-element]

The thought that sparked this issue: I cloned foam in October and I know I was a bit of an early adopter, and I want to benefit from further updates to foam.

If in contrast, all tech changes are fully encapsulated in the foam app updates and the foam development anticipates never having to update contents of the templates folder, then this feature is unnecessary and should be closed.

[riccardoferretti]

I think that's the main question and where the template meets the generator. It would be helpful to have specific examples, e.g.:

• new extensions that were recommended in template, but aren't available to early adopters
• new settings / defaults
• updates to publishing template/configuration/...

Several of those feel also a bit "dangerous", where nothing should happen without user consent, as the risk of changing a default but desired behavior is real. (e.g. changing wikilinks to have or not the extension in the name would break an existing repo, we definitely wouldn't want to automatically push such an update of the template to existing users). I am wondering if there are no-brainer cases.

It almost feels like what is needed is a "sanity check on best practices" command, or a "here is what has changed in the template you started with", ... that is driven by the extension. Brainstorming here.

[cmcconomy-element]

A concrete example - here is settings.json from my pull:

{
  "editor.minimap.enabled": false,
  "editor.wrappingIndent": "indent",
  "editor.overviewRulerBorder": false,
  "editor.lineHeight": 24,
  "workbench.colorTheme": "Gray Matter Light",
  "[markdown]": {
    "editor.quickSuggestions": true
  },
  "git.enableSmartCommit": true,
  "git.postCommitCommand": "sync",
  "files.exclude": {
    "**/node_modules": true
  },
  "files.watcherExclude": {
    "**/node_modules": true
  },
  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
  "vscodeMarkdownNotes.slugifyMethod": "github-slugger"
}

and here is the current settings:

{
  "prettier.singleQuote": false,
  "editor.minimap.enabled": false,
  "editor.wrappingIndent": "indent",
  "editor.overviewRulerBorder": false,
  "editor.lineHeight": 24,
  "[markdown]": {
    "editor.quickSuggestions": true
  },
  "git.enableSmartCommit": true,
  "git.postCommitCommand": "sync",
  "files.defaultLanguage": "markdown",
  "files.exclude": {
    "**/node_modules": true
  },
  "files.watcherExclude": {
    "**/node_modules": true
  },
  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
  "vscodeMarkdownNotes.slugifyMethod": "github-slugger",
  "foam.edit.linkReferenceDefinitions": "withExtensions",
  "foam.openDailyNote.directory": "journal",
  "foam.openDailyNote.titleFormat": "fullDate"
}

in my case no new recommended plugins were issued - yet (though I anticipate image-paste ;))

I guess any changes to .vscode should somehow be able to be merged - either as defaults or at least a dialog or a changelog that recommends making changes?

[riccardoferretti]

the more I think about it, the more this sounds like some sort of db migration, again with all the associated challenges and conflict management. maybe this configuration shouldn't be managed by the template, but by the extension

[cmcconomy-element]

I echo the sentiment that the extension is the place for this.

The way I think of Foam is as the extension that ties together all these capabilities into a single package that permits me to author linked documentation, and as such it should contain all the application logic. In addition, this means the natural extension-update mechanism baked into VSCode can help me maintain it up to date without doing behind-the-scenes cloning and merging.

The template on the other hand should constrain itself to just be an example document structure to help bootstrap people.

my opinion of course.

[cmcconomy-element]

Also note, I think this should be easy to shift to the extension: https://code.visualstudio.com/api/references/extension-manifest

see extensionDependencies

[leonhfr]

Also note, I think this should be easy to shift to the extension: https://code.visualstudio.com/api/references/extension-manifest

see extensionDependencies

On this, extensionPack might be a better fit if we go this way. extensionDependencies would make the current recommended extensions mandatory. Some (most?) people would like more granularity.

Defining an Extension Pack now uses a new property called extensionPack instead of extensionDependencies in package.json. This is because extensionDependencies is mainly used to define functional dependencies among extensions that prevents uninstalling or disabling an extension dependency without uninstalling or disabling the dependent extension.

An Extension Pack should not have any functional dependencies with its bundled extensions and they should be manageable independent of the pack.

Source: https://code.visualstudio.com/updates/v1_26#_extension-packs-revisited

[leonhfr]

Also note that vs code is working on allowing extensions to display the changelog, similar to the What's new? it does when updating. So it might just be a case of waiting until it's implemented.

Source: https://github.com/microsoft/vscode/issues/102139

[leonhfr]

Another option is to make use of this submodule: https://github.com/alefragnani/vscode-whats-new

This submodule is used to display a What's New page on my VS Code extensions. It has a simple (but yet effective) UI, optimized to display all the information in a single page.

Foam could also rely on a temp solution like this submodule while vscode implements the more general feature (see previous comment).

[leonhfr]

I had an idea on this. For the foam-template, we want the difference between the moment the user's repo was generated and the current template. So at its most simple it's a diff between commits. If we know the commit from when the user generated the repo, we know what updates have been applied since.

Additionally, if Foam makes this function available as a command or something, and a user applies the update at some point in time, Foam could store the latest commit id, and only diff from this one when the user uses the command next time (could makes use of .vscode/foam.json?).

We can even filter out the non-critical directories, and only keep the one we want. For example, we are only interested in changes in .vscode and the last commit when we used the template was a82e516.

$ git diff a82e516 .vscode

Results in:

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 1bf2c50..5747da4 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -5,12 +5,6 @@
     // Foam's own extension
     "foam.foam-vscode",
 
-    // Prettier for auto formatting code
-    "esbenp.prettier-vscode",
-
-    // GitLens for seeing version history inline
-    "eamodio.gitlens",
-
     // Tons of markdown goodies (lists, tables of content, so much more)
     "yzhang.markdown-all-in-one",
 
@@ -18,6 +12,9 @@
     "kortina.vscode-markdown-notes",
 
     // Image-pasting for markdown
-    "mushan.vscode-paste-image"
+    "mushan.vscode-paste-image",
+
+    // Spell checking for text, markdown and latex
+    "ban.spellright",
   ]
 }
diff --git a/.vscode/settings.json b/.vscode/settings.json
index f2d04a0..61017e8 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,5 +1,4 @@
 {
-  "prettier.singleQuote": false,
   "editor.minimap.enabled": false,
   "editor.wrappingIndent": "indent",
   "editor.overviewRulerBorder": false,
@@ -7,8 +6,6 @@
   "[markdown]": {
     "editor.quickSuggestions": true
   },
-  "git.enableSmartCommit": true,
-  "git.postCommitCommand": "sync",
   "files.defaultLanguage": "markdown",
   "files.exclude": {
     "**/node_modules": true
@@ -16,11 +13,17 @@
   "files.watcherExclude": {
     "**/node_modules": true
   },
-  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
-  "vscodeMarkdownNotes.slugifyMethod": "github-slugger",
   "foam.edit.linkReferenceDefinitions": "withExtensions",
   "foam.openDailyNote.directory": "journal",
   "foam.openDailyNote.titleFormat": "fullDate",
-  "pasteImage.path": "${currentFileDir}/images/${currentFileNameWithoutExt}",
-  "markdown.preview.breaks": true
+  "git.enableSmartCommit": true,
+  "git.postCommitCommand": "sync",
+  "markdown.preview.breaks": true,
+  "pasteImage.path": "${projectRoot}/attachments",
+  "pasteImage.showFilePathConfirmInputBox": true,
+  "prettier.singleQuote": false,
+  "spellright.notificationClass": "warning",
+  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
+  "vscodeMarkdownNotes.slugifyMethod": "github-slugger",
+  "window.autoDetectColorScheme": true,
 }
diff --git a/.vscode/spellright.dict b/.vscode/spellright.dict
new file mode 100644
index 0000000..29e285f
--- /dev/null
+++ b/.vscode/spellright.dict
@@ -0,0 +1,2 @@
+wikilink
+spellright

(BTW I just used this methid to update my own Foam workspace with the latest recommendations. Can confirm it works :ok_hand: )

[jmg-duarte]

What is the status on this?