Enhancement: Enable/support an editorial workflow.

[iveptawebadmin]

Is your feature request related to a problem? Please describe.

It is common to have a 'staging' branch and preview site/sandbox based on that branch for editorial review/approval. When the edits are reviewed and approved, then that branch is merged into the main 'production' branch.

Describe the solution you'd like

Scripts/Tools in the UI to help with this workflow.

• Start with an Issue in the target project repo for the content to add/edit.
• Create a task branch or checkout the staging branch to resolve the issue.
• Create a PR or Merge Request for that branch into the 'production' branch.
• Send the edits in the PR/MR and the preview URL to the Editor for review and approval.
• On approval, merge the PR/MR to production.

Describe alternatives you've considered

A lot of this can be done outside of the system, but it requires some skill in git, repo tech, etc. to make it happen and many 'content editors' who would use the CMS would not know or want to learn the 'coding' side of the process/system to make some edits and pass them for review

Additional context

Other tools have a built in editorial branching and merge to production process through the CMS UI.

[zivbk1]

I will say that as the OP, this is a very low priority request. I have taught some non-technical folks to use VSCode source control features to do what needs to be done outside of the Frontmatter tooling. It really isn't that difficult and will probably be different for every project. I would not feel bad if this issue was closed for being out of scope for this project.

[estruyf]

Thanks for the feedback @zivbk1. Let us keep it open so others could maybe come in and share ideas on it.

[bwklein]

@bwklein I used to manage an editorial team for a tech media property and the writers flung around Word and Google docs(some used Markdown) until they were approved. #195 seems like it could solve from approved to publish (prepping the technical side - SEO, images, etc.), but I wonder how many writers would feel comfortable with the overall workflow.

A lot of this can be done outside of the system, but it requires some skill in git, repo tech, etc. to make it happen and many 'content editors' who would use the CMS would not know or want to learn the 'coding' side of the process/system to make some edits and pass them for review

I think the problem to solve is the "staging" and production branch navigation, since most SSGs have a dev server you can spin up. Isolating work on staging along with keeping the status of draft would provide the workflow you are looking for I believe, and it provides a pseudo scheduling mechanism.

Just my two cents.

Originally posted by @apowell656 in https://github.com/estruyf/vscode-front-matter/issues/377#issuecomment-1202342686

[apowell656]

Another thought I had is most SSGs deploy off the main/production branch, so isolating the editorial changes on staging would limit the deploys to only production ready content.

On staging (in a perfect world): approved article/content -> change status of content (the default status for this branch should be "draft") -> branch merged to production and synced (with possibly an action called "publish" that only shows on the staging branch). I can imagine this getting complicated with a huge team, but I think it could work.

[bwklein]

@apowell656 for our project we use GitLab + GitPod to make it happen.

Work starts with a GitLab Issue for the additions/changes to be made to the content.

GitLab has a button in the Issue UI, that will make a task branch and Merge Request for that branch back to main with one click.

From the new MR you can click into the task branch in GitLab and open GitPod in that context.

In GitPod we use FrontMatter CMS to manage content, creating a new content item from a known content type in the FM Dashboard.

The date field in the content type UI is for the desired publishing date. Which the Editor sets to the date they want the content to be public. We don't have a 'draft' field, since the process we use combined with the publishing date allow the Editor to keep the work in draft status (not merged to main) and not shown on the site until after the specified date.

GitPod provides a Live preview of the site and content they are working on. Showing them exactly how the content will look in production. This environment shows all drafts and future content in the preview. The live preview URL can be made public and shared with others who want to see the changes made to the content while it is being edited. The GitPod workspace can also be shared for live collaborative editing of the content.

The person is saving changes in the GitPod workspace.

(Here is where some tooling might be handy and editors struggle a bit.)

Now Git comes in... They must switch to the Source Control panel on the left, leaving the FrontMatter panel.

1) Pull from remote Origin/Main to get any new changes to the site from other contributors.

a) Might result in merging changes to the file they are working on, which requires merge conflict resolution.

b) Might block the pull and require local changes to be stashed and then popped back into the local workspace to 'clean' the workspace.

2) Stage the changes in the local repo.

3) Write a Commit message about the staged changes made. Following our Commit message standards. Commit the changes.

4) Sync the commit up to the task branch on GitLab.

From there they can close the GitPod workspace.

CI/CD on GitLab kicks in and builds/deploys a preview of the branch in the Merge Request. This URL is added to the description of the MR as part of the CI/CD process. The content creator/editor can invite someone to review the MR which shows the preview and changes made to the site source. Comments, change suggestions, etc. are made in the GitLab MR by the Reviewer. The Editor resolves those threads in GitLab UI directly or by opening up GitPod again from the Branch for more complex edits.

Once approved by the Reviewer and all threads are resolved, the Editor can click to Merge the branch back into main by clicking a button in the GitLab Merge Request UI.

Now, we have another CI/CD task that builds all commits to 'main' branch and publishes it to a 'staging' URL. It builds the site in 'production' more, so future posts and posts with 'draft: true' in front matter are not shown.

This is the preview of the site as it will look to the public. It can be shared with others for final review.

If it looks good, then there is a manual action (button) in the GitLab Pipeline UI than can be clicked to deploy the staging build artifacts to the Netlify production URL. The changes go live.

Whew! It's a lot of deliberate steps to take the site code from one state to another. Allowing for different editing and review opportunities along the way. But it is a bit rough for newcomers, or people who aren't in the system editing frequently.

Maybe pulling some of the steps into button/scripts in the FrontMatter CMS UI would help smooth some of the flow within GitPod, to get the changes in the workspace up to the GitLab branch they created. Merge conflicts are just a sticky point that I don't know how to avoid in a Git-Backed CMS. Fortunately, the UI for this in GitPod (VSCode) is pretty good, but it can be a bit confusing to figure out all the things you need to click to resolve the conflicts. A real-time collaborative editor like Google Docs avoids this issue, but that's a completely different tool outside of the rest of the infrastructure. We need something like Google Docs, that mounts to a git repo and provides easy collaboration, conflict resolution, commenting, notes, etc.

I see FrontMatter CMS as a potential solution. To provide this tooling in a slick UI. But would require a new editing tool for page content, that could do the things that Google Docs can do.

[apowell656]

@bwklein yep complicated ;-). That is a lot of steps and I believe you are correct. Newcomers and people that don't do a lot of editing would have to get comfortable with your internal process.

The team I worked with used a proprietary CMS, maybe 600% worse than WordPress or Joomla combined.

[estruyf]

Ok, I'm blown away 🤪. Joking aside, that is a complicated flow, and I see FM playing a part in it. When FM does this, it would require actual GIT information to open PRs, switch branches, ...

[bwklein]

This might be useful for GitLab. https://www.npmjs.com/package/@gitbeaker/node