git integration

[maxyurk]

I saw the "Version control - coming soon" homepage block.
This is the main feature I'd need to try and push for vrite adoption at my workplace. I want to replace all google docs for feature specs and on-boarding guides and other internal documentation etc with vrite.
I have some thoughts about version control integration. I used https://github.com/getgrav/grav in the past and I have some experience with their git integrations.

The main decisions I can think of are (1) what to commit, (2) when to commit, (3) where - which repo & branch, and (4) conflict resolution.
Regarding (1) & (3) - I think it's a workspace git integration config. Maybe have include patterns. All included markdown files will be loaded to a default column ("published"?). Upon creation of a new page you can opt in to include it the tracked files or just always track all.
Regarding (2) when - I think we can use the groups (columns) to trigger commits. For example when moved from "draft" to "published". Maybe a published document must move back to "draft" for editing.
(4) Nice UI for conflict resolution would be great, but something as simple as default's vscode conflict handling is good enough.

We'll probably need a "refresh" button.

I had a bad experience with grav that had periodic commits, I don't think it's a good direction.

[areknawo]

Right out of the gate - thanks for the great insights!

Git integration is planned as one of the most important features for the stable release. It'll take some time as there are many things to implement to get Git integration right.

In general, I think that the planned Git support should address the points you've made. I'm primarily inspired by Git workflow in code editors like VS Code, and I'll try to replicate it to some extent. The idea for a possible workflow looks like this:

• For context:
  • The dashboard will be extended beyond Kanban to support additional "Views", e.g. list view (as preference), and folder view (for better representation of content management in Git-reliant workflows, like docs, internal guides, etc.)
  • New Content Piece Variants feature will be added that allows for multiple "variants" of the same content piece to exist while still being grouped into one (for i18n support and other use cases);
  • The editor will support custom content blocks through Extensions;
  • Extensions will have support for providing Content Transformers (now available in the JS SDK and Export menu) which will be used throughout the system (extending the Export menu and facilitating Git integration)
• Git integration is a separate side panel with the same workflow as found in code editors;
• Git integration has to be configured likely for the entire workspace. This includes settings like:
  • What provider to use (GitHub will be the first one supported, with GitLab, and Bitbucket coming later on)
  • How to "map" content to Git, likely in the form of a path pattern. This pattern could consist of (by then nested) content groups, available variants, and other metadata;
  • What Input and Output Content Transformers should be used to transform content to the format that should be used in Git;
  • General Git settings like repo and branch;
• Conflicts and anything at the "Git-level" will be handled on the already-transformed content with Monaco Editor; Anything right in the Vrite Editor will be quite difficult to implement and isn't planned for the stable release;
• In general, only the basic, required Git operations are guaranteed to be supported at the start (e.g. push, pull, commit, stage, refresh, and resolve changes);

I think, if this can be achieved, it'll make for a pretty comfortable and versatile workflow. I'm happy to learn what you think of this plan.

On a side note, the "Version control" on the main page refers to a different, in-editor feature, similar to Version history in Google Docs. Vrite already stores the history of edits done to the file (though it is currently reset when the content is updated via the API) and the goal is to provide a UI (and API) that allows you to navigate through this history and revert back to previous steps.

[maxyurk]

(feel free to close the discussion if you want)

[areknawo]

Thanks. Will keep this open until Git integration is implemented so that other people can leave their thoughts/opinions here.

[areknawo]

@maxyurk Basic Git integration via GitHub (pull, commit, resolve conflicts) for syncing Markdown content was added in v2023.8.11. In case you're still interested, this may cover your original use case. Other Git sync features will be added as described in the following weeks.

[aes2000]

Please, don't forget about gitea (https://about.gitea.com/)

[areknawo]

Will add Gitea to the list. Other providers are definitely on the table, but there's no specific timeline for them yet.