Enabling the editorial workflow

Adding some new content

To start the editorial workflow, let’s first add some new content. Start the development server by running gatsby develop, then open the CMS at http://localhost:8000/admin.

We’ll add a new category and product to the menu. Go to “Pages,” then click “Menu” to open the coffee shop menu. From the menu page, click “Add category.”

In the upper right corner, you might notice that this time, the “Published” button did not change to “Publish.” Instead, there’s a new “Save” button at the top of the page, as shown in Figure 13-1.

To save the new changes, click this “Save” button. We have now triggered the editorial workflow. There are a few new buttons at the top of the page now, shown in Figure 13-2.

Let’s take a look at what happened behind the scenes.

Viewing the pull request

When this draft change was saved, a new branch was created in the Git repository, the changes were saved to that branch, then a pull request was opened for that branch against the master branch.

A pull request is a request to merge, or pull, a set of changes from one branch into another. The changes can be viewed in the GitHub web interface, and code review comments can be left. Open your browser, and go to your coffee-shop repository on GitHub – https://github.com/<your-username>/coffee-shop.

If you look at the tabs at the top of the repository page, you’ll see that there is one pull request. Click the “Pull requests” tab to view the open pull requests screen. You should see a pull request for the changes we just made, as shown in Figure 13-3.

Click the title of the pull request to open it. You’ll see some more detailed information about the pull request, as shown in Figure 13-4.

If you click the “Files changed” tab, you will see a view showing the differences between the master branch and our draft changes, as shown in Figure 13-5.

In this view, we can see the new menu category that we added and the single item we added as well.

Back on the “Conversation” tab, you will see that the pull request currently has a netlify-cms/draft label applied to it. This means the changes are still in draft status. You can make further changes in the CMS user interface, and when they are saved, they will be added to this pull request .

Viewing the preview

One of the nice things about the editorial workflow is that it publishes a preview version of the site containing your changes so that you can see them in a live version of the site before the site is published. In your browser, return to the CMS application and go to the menu page. At the top of the screen, you will see a link that says, “Check for Preview.”

Click that link, and after a moment, it will be replaced with another link that says, “View Preview.” Click the “View Preview” link. A new browser tab will open showing the coffee shop site. If you look at the URL, though, it will be different. Instead of https://<your-site-name>.netlify.app, it will be something like https://deploy-preview-1--<your-site-name>.netlify.app. The preview is deployed to a separate URL so that it can be viewed without updating the main live site.

From this preview, click “Menu” in the navigation menu at the top right. You will be taken to the menu page which will include the new Bakery category that we added, as shown in Figure 13-6.

Updating the status

Let’s go back to the CMS. At the top of the screen is also a button labeled “Set status.” Click that button, and you will be presented with a dropdown menu of different status options. As we saw when viewing the pull request, this change is currently in “Draft” status. The menu is shown in Figure 13-7.

Next, click “In review” to update the status. If you return to the pull request on GitHub, you’ll see that the label now reads netlify-cms/pending_review. We can view the changes and add review comments. Click the “Files changed” tab again, where you will see the difference view.

If you hover over a line of text in this view, you will see a blue button with a plus sign appear, as shown in Figure 13-8.

If you click that button, you will be presented with a form where you can add a comment for that line. Enter some text, then click the green “Start a review” button, as shown in Figure 13-9.

At the top of the page, you will see a new green button labeled “Finish your review.” Click that, and you will see a form for finishing the review, as shown in Figure 13-10. There is a radio button labeled “Approve,” but we are unable to click it because a pull request author cannot approve their own pull request. In a normal situation, another member of the team would view and approve this pull request.

Finishing up

Let’s imagine another member of our team has approved the pull request. Go back to the CMS, open the menu page, and change the status to “Ready.”

If you go back to the pull request, you will see again that it has a new label: netlify-cms/pending_publish. This means that all changes have been approved and it is ready to be published. We can do that now by going back to the CMS and clicking “Publish,” then “Publish now,” as we normally would.

You may be asked to confirm that you want to publish this entry. Click “OK” to continue with publishing. The status in the top right of the page will change to “Published” after a short delay.

Go back to the pull request one more time. You will see that it is now in a “Merged” state and the branch has automatically been deleted, as shown in Figure 13-12.

Summary