Pull request creation and link in editor UI

[rdebeasi]

Is your feature request related to a problem? Please describe. We use editorial workflow to allow contributors to add new content. We use pull requests to review content and either request changes or merge the content. With the current UI, this workflow is tricky for a few reasons:

• There's no link between the CMS and the pull request that it generates.
• Contributors save a draft, not realizing they've created a PR. Moderators manually indicate which PRs are ready for review by adding comments.
• Contributors see a "publish" button in the CMS and try to click it. If the master branch is protected, clicking this button causes an error. Otherwise, clicking this button causes the PR to be merged without review.

Describe the solution you'd like I'd like to see a configuration flag that replaces the "publish" button with a link to create or view a pull request. In this mode, "draft" and "ready" status would be used as an indicator of whether a PR has been created.

Mockup of "draft" status:

Mockup of "ready" status:

Describe alternatives you've considered

• We've tried protecting master to disable publishing, but doing so breaks media uploads (#1344).
• We added a feature request for showing draft/ready status as a label in a pull request (#1617). Many users don't seem to realize that they're creating a PR by saving a draft, though.
• There's a proposal for an allow_publish flag (#1298) to disable publishing within the CMS. This feature would help prevent users from publishing content without review, but it wouldn't clarify which PRs are ready for review or show the user that the next steps happen in a PR.

[erquhart]

First let me say how helpful it is to have this kind of feedback from teams using this in production - thank you for the details.

It's clear that you're using both the CMS and GitHub's pull request UI to moderate content. Can you provide a brief step-by-step of how a piece of content goes from first draft to published with your current setup?

[rdebeasi]

Sure! We actually have a step-by-step contribution guide for contributors. The short version is:

1. The contributor logs into Netlify CMS with a GitHub account. (Many of our contributors are new to GitHub.)
2. The contributor adds a new practice in the "practices" collection. A PR is created behind the scenes when the practice is saved.
3. If the PR appears to be a work in progress, a moderator will comment on the PR to indicate that it's not ready for review. The moderator will update the PR when it is ready for review.
4. Moderators comment on the PR. They might ask for changes before the PR can be merged, or they might file new issues for future changes.
5. The contributor receives an email and returns to GitHub to reply.
6. If necessary, the contributor goes back into Netlify CMS to make the requested changes. The contributor then returns to GitHub to say something like, "I've made the changes! Please review again."
7. The moderator replies to say something like, "Looks good - thank you!" and merges the PR to the staging branch. The staging site is deployed.

Periodically, a moderator merges from staging to master to deploy the production site. (We're currently deploying to production every few days.) We've discussed improving the release workflow in the future.

Please let me know if you have any questions. Thanks for building an awesome product and running a thriving community! :rocket:

[erquhart]

The reason we're abstracting over the underlying PR is that, ideally, content editors shouldn't need to know or care about the Git side of things. Lack of robustness makes this challenging for demanding use cases like yours, but in the end, what you really want is less GitHub for your editors, not more.

If I'm understanding correctly, optimal support for your use case requires:

• authentication that doesn't require the editor to have a GitHub account
• comments/feedback within Netlify CMS (opening separate issues for future changes within Netlify CMS is also an interesting concept)
• email notification for the editor when comment/feedback occurs
• ability for moderators (or even editors) to work within GitHub if they like

There are potential solutions for all of these, including #1850/#53 and #1669, but the email notification bit is tricky if that notification should be triggered from and lead back to Netlify CMS. Have to give that a think.

[rdebeasi]

Yeah, I think you summed it up nicely. (#1617 would also be useful.) It would be great if contributors didn't need to context-switch and could do everything in either GitHub or Netlify CMS.

That said, there's a surprisingly large amount of functionality in issues and PRs that would have to be abstracted away in Netlify CMS. If I were implementing these features, I would be worried that I might accidentally rewrite GitHub. :wink: Do the benefits of that abstraction justify the additional complexity?

Thanks again for looking into this!

[erquhart]

The functionality we'd cover in Netlify CMS would work the same regardless of the backend in use (though each backend would need to provide an implementation). All I'm envisioning for now is review/discussion (comments in GitHub) and annotations for things like entry status (labels in GitHub).

[rdebeasi]

Cool, that sounds great to me. That would be much nicer than having a link to the GitHub PR.

Would you like me to close this issue and/or file new ones? Is there a label that I could use to keep track of editorial workflow issues?

[erquhart]

This can be kept open as it covers a specific use case on top of the underlying requirements. Looks like you found all of the related issues, you can add #1669 as well for using PR labels to indicate workflow participation.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[rdebeasi]

Not stale. Thank you!!

[erquhart]

We should consider an optional link to the underlying PR/MR. The stuff I mentioned would be great but we need a stopgap.

[lbarker]

@erquhart Hello! We've implemented Netlify CMS for our GitLab marketing website and need this feature verbatim. Our issue for this is here.

In the current state, our content editors must create a draft in Netlify CMS, go back to GitLab to find the merge request, and then view the review app to preview changes. We have this process documented in our handbook here.

Having a direct link from the draft in Netlify CMS to the merge request in GitLab would be a significant feature for our content editors.

A possible stopgap solution is linking directly to the branch open in GitLab/GitHub. This still requires the user to navigated to the MR from there, but it is more direct. Here's an example branch in GitLab opened from Netlify CMS for our use case.

Could we add a link to the Netlify CMS editing UI after a draft is successfully saved & branch is opened? I imagine the link structure could be something like this: repo/-/tree/cms_label_prefix/collection_name/{{file_name}}

[erezrokah]

Hi @lbarker, see @erquhart comment about abstraction:

The reason we're abstracting over the underlying PR is that, ideally, content editors shouldn't need to know or care about the Git side of things. Lack of robustness makes this challenging for demanding use cases like yours, but in the end, what you really want is less GitHub for your editors, not more.

May I suggest another approach for your use case?

1. The CMS supports preview links, which means that if you add a commit status to your PRs with a URL, the CMS should show it in the editor (see https://www.netlifycms.org/docs/deploy-preview-links/#using-deploy-preview-links). From there editors should be able to directly access whatever external page you'd like.
2. For assigning PR reviewers - ideally we would allow that in the CMS, but would using code owners work for your use case. I can see it's already configured in the repo.