Releases

Releases allow you to set up collaborative workspaces where future sets of content can be worked on in real-time. Content can be created, edited and deleted in the workspace and then scheduled for publishing at a future date. Scheduled publishing allows your content to "go live" automatically - merging your content changes back into the mainline while triggering release actions for things like:

• Email Notifications
• CDN Synchronization
• Web Hook Calls

Releases give your content team the ability to use Scheduled Publishing. Releases build on top of the underlying Branching capabilities of Cloud CMS. They utilize branches under the hood while providing easy-to-navigate workspaces, activity tracking and scheduled publishing. Releases are often used to produce a final content production for release at a future date, often to a web site, mobile applications, catalog or external data store.

How Releases Work - An Example

Let's imagine that you're using Cloud CMS to publish content for a digital online magazine. The magazine is delivered via a front-end web site. Our goal is to create some new content, push it live and then inform the web site when the new content is available.

You'd start by creating a Friday release. Once it is created, your team can switch to the Friday release within the user interface and create content just like they always do. They use forms, they use workflow, they build new and interesting stuff.

When they're happy with their changes, they "finalize" the release. Finalizing the release tells Cloud CMS to look at any other releases that are already finalized and scheduled and which may conflict with your release. If conflicts are discovered, they are recorded and your team will be given that task of resolving those conflicts.

For example, suppose that while you were busy working away on the Friday release, a separate decision was made to release a "quick fix" update for Wednesday. Perhaps some new content was added to the Wednesday release that your Friday release would not have. If the Wednesday release were already Finalized and locked in, then when you try to Finalize the Friday release, Cloud CMS will discover this discrepancy. In this case, it will automatically solve this for you and pull the Wednesday content into your Friday branch for you.

However, what if the Wednesday branch did something like delete a piece of content that you updated in your Friday branch. In this case, pulling the Wednesday deletion ahead into Friday would delete your changes. Obviously, this isn't what you intended and so this is recorded as a "merge conflict". A merge conflict is basically an excuse to grab a cup of coffee and walk over to your coworker's office to have a chat. You will need to figure out between the two the right course of action for Friday - either keep your changes or delete or something else.

Most of the time, you won't have to deal with conflicts. You're naturally work stuff out ahead of time through conversation so you won't step on each others toes. But if you do, then Cloud CMS provides a few really good options for manual conflict resolution including:

• side-by-side content forms
• visual comparison
• JSON differencing
• inline editing (A vs B)

Once all the conflicts are resolved (or if you didn't have any), your Release will be finalized. This means that it can be successfully merged with the master branch because all of the potential issues were ironed out ahead of time.

You can now Schedule the release. Scheduling the release adds it to the Cloud CMS scheduler so that a background process will kick off on the release date. The release date is a specific date and time when the release is intended to go live. When that moment arrives, the Cloud CMS scheduler will start the release process for your release.

The release process involves:

1. Merging your release branch content back into master
2. Taking a snapshot of the master branch
3. Some book keeping to mark the release as "released"
4. Sending any notifications via SNS to load message queues with release availability information
5. Firing any release actions

Once the release process completes, all of the content from your Release branch will be available on the master branch. In addition, a snapshot is taken. A snapshot is a special kind of branch that is used to capture a frozen-in-time moment of your repository. Snapshots are just like regular branches except that they're read-only.

At this point, you usually want to inform your front-end web site that new content is available. This is typically done by listening for SNS notifications (which are delivered via SQS queued messages to your application server) or by registering a custom HTTP endpoint and receiving an HTTP call to notify that the release went live.

If your web site is making dynamic calls to Cloud CMS, you can have it switch branches to the new snapshot branch that was produced as part of the release process. This snapshot effectively captures that moment in time when the release went live and contains the merged content.

Enabling Releases

To enable releases, you must be a Project Manager. You can then go to the Project Settings page and select the Releases page from the left-hand menu.

Enable the checkbox for "Enable Releases for this Project" and click Save.

Customize your Release

Once Releases are enabled, you can further customize them to do your bidding.

The following options are available:

• Master Branch can ONLY be updated via Releases

When this option is enabled, the only way to make updates to the master branch will be via Releases. A Release will need to be created, scheduled and then released in order for the master branch to receive new content. Upon release, content from the Release branch is merged into master.

If users try to save content against the master branch directly, an error modal popup will appear informing them that the master branch can only be updated via releases.

• Maximum Number of Active Releases

In some cases, you may want to limit the number of concurrent releases that are being worked on. This caps the number of concurrent active releases that are in flight. You might use this to inspire your content team to make decisions about old releases that were created but not completed. Or you may inspire the team to work more closely together on activities that are correlated. Either way, capping things can have some positive impact since it drives people to collaborate more closely.

• Release Actions

When a scheduled release goes live, it does a number of things. For example, it merges to the master branch and also creates a snapshot of your repository at that moment in time. You may want to have some custom stuff happen at this point such as firing off an HTTP call to a custom web hook or sending an email.

See the section below for more detailed documentation about the kinds of release actions you can set up.

The User Interface

When Releases are enabled, they are available on the left-hand side under the "Releases" menu.

The user interface provides three ways to view your releases, both past and future.

• Calendar
• List
• Network

The Calendar view provides a day-to-day view of the scheduled releases so that you can see visually what is coming up and where sources of conflicting or mergeable content may reside. You can, in effect, see what other folks are working on.

The List view provides a list of your releases and allows you to see things like the intended release dates, scheduling activities and more. It also allows you to sort releases by interesting fields so that you can more easily find things.

The Network view provides a subway-map of your releases and reveals how they're all connected together. This is useful for complex release hierarchies as it reveals where in the topography a release was branched and where it was merged back into the main line.

What are Conflicts?

A Conflict occurs when any two people make changes to the same piece of content such that their changes are incompatible. In this case, Cloud CMS identifies the issue and asks the editorial team to determine which of the two sets of changes to keep.

Here's a simple, real-world example.

Suppose you'd like to plan a birthday party for your father. There are two things that are needed:

1. Balloons
2. Party Hats

Fortunately, you have a sibling (a brother). He offers to go off and get the balloons. And you go off to get the hats.

This is really wonderful because it means you don't have to do both things yourself. You guys can split up and do the work in parallel. Unfortunately, this also means that if you're not perfectly informed about what is to be done, mistakes can be made.

Suppose you now have the Party Hats and your brother has the Balloons. You get back together and share what you've acquired.

1. The Balloons say "Happy 80th Birthday" party"
2. The Party Hats say "Happy 85th Birthday party"

Uh oh. Something is amiss.

There is a conflict in that you have different birthdays. Which birthday is it? In both cases, something has been asserted about the state of your Father's age. Are both of them wrong? Is one of them right? Or are they both wrong?

In Cloud CMS, multiple people can work on content at the same time in different isolated Release workspaces. This is akin to people running off to work on tasks on their own. And then, at some point, everyone brings the content that they worked on back together.

Cloud CMS automatically detects cases where two or more people may have modified information that conflicts. This is simply known as a Conflict.

Conflicts are good things. They are reasons for the people involved to become aware of changes that others have made that disagree with their world view. They are reasons for people to then discuss and work out what is actual and intended ahead of "going live" or "publishing".

In the contrived but well-intended scenario above, a detected conflict is a reason for you and your brother to catch the fact that one or both of you have his age wrong. You can then agree on it and fix it and make sure your efforts are aligned ahead of paying for things (or setting up for the party).

Conflicts with Master Branch

One of the most common reasons that you might get a Conflict reported to you is if someone changed something on the Master branch before you had a chance to merge.

Let's look at an example.

Suppose that it is Monday.

On the Master branch, you might have a piece of content that looks like this:

You now create a Wednesday Release. When you create the Wednesday Release, you're essentially describing a future timeline. Kind of like in Back to the Future. You're describing a future idea of what the world should be like on Wednesday. That future timeline forks off from today. It's a version of today advanced two days into the future.

On Tuesday, you work on the Wednesday Release. You change the title of piece of content. And then you schedule it to go live the next day.

The next day, you wake up and check to discover that your content changes went live. No problems at all. This works because there were no conflicts at all.

This scenario looks like this:

Now suppose that you had exactly the same scenario. Except this time, when you were working on it on Tuesday, a colleague of yours made a change to the piece of content on the Master Branch. In fact, they make a change that is incompatible with your change!

On the Wednesday Release, you adjust the title to indicate that the Brewers "win" the World Series, like this:

Meanwhile, on the Master branch, someone elects to update the title to reflect more information about the Milwaukee Brewers by noting that it's the 2020 team we're talking about:

The Master Branch was changed directly, thus it represents the "real" state of the world. The Wednesday Release has a different value that is disconnected from this reality. Until such time as we try to finalize and Schedule the Release to merge with Master.

Then we get a Conflict. Cloud CMS will detect that the Master branch has changed and that the version of this document on the Master branch has a property-level conflict. The conflicting property is title and it has two competing values:

• Milwaukee Brewers play in the 2020 World Series! (already committed to Master)
• Milwaukee Brewers win the World Series! (staged on the Release, wanting to commit)

When you try to Finalize and Schedule, the Conflict will be detected and it will be reported back to you

If you click on Review Conflicts..., you'll be taken to a screen that shows all of the other Releases (and other Branches) that the current Release has a Conflict with. In this case, there is only one conflicting Branch and it is the Master Branch.

Click on View Conflicts... to view the Conflicts that the Wednesday Release has with the Master branch.

You will now be presented with a list of all of the Nodes that are in conflict between the Wednesday Release and the Master Branch. As expected, there is only the one document.

Click on the Resolve... action button for the document to dig into the document and resolve any property-level conflicts. In this case, there is only one property-level conflict. It is for the title property.

There are two tabs available here.

The Visual tab lets you see the properties broken out in a table with a two-column, side-by-side layout. For each row in the table, click on Keep My Version to keep your own version of that property or click on Keep Their Version to replace your property value with the other value.

Click on Save Resolutions to save your changes.

The JSON tab lets you edit the JSON for the local content (on the Wednesday Release) to manually fix any property conflicts that may arise. The visual editor shows side-by-side JSON editors and shows the differences between them so that you can make modifications straight away.

Click on Save Local Changes to save the changes to your local branch.

Suppose in our scenario that we'd like to take the two values:

• Milwaukee Brewers play in the 2020 World Series! (on Master branch)
• Milwaukee Brewers win the World Series! (on the Release)

And merge them to this:

• Milwaukee Brewers win the 2020 World Series!

We can do so by using the JSON tab to change the local version, like this:

We click on Save Local Changes to save our changes.

We then use the breadcrumb to click back to the list of Conflicts with Master:

Sure enough. We now see the updated Conflict with our new local value:

Click on Resolve... and then click on Keep My Version.

Click on Save Resolutions to save your changes. You'll be taken back to the conflicts listing. A green check mark will indicate that you've provided a resolution for the Conflict:

Go back to your Release and run Finalize and Schedule again. And this time, the Release will lock in and be scheduled to go live.

To recap, Cloud CMS detected the Conflict and let you decide what to do about it. The easy answer is to pick one title or the other. But in this case, we provided a new title that brought together the intentions of the changes to the Master branch with those of the Release.

You might ask - how would you know what the person who worked on the Master branch was doing or why they made those changes? That's a good question. And it's one that can only be answered by communicating with your teammates about your team's content strategy and publishing goals.

Cloud CMS provides some very powerful tooling for scheduling releases and for detecting these kinds of Conflicts. However, it is still up to you and your team to work together to make sure that everyone is on the same page and pushing toward the same content strategy goals.

Locking the Master Branch

In the previous example, we looked at how Conflicts could be detected against changes in the Master Branch. This is helpful for understanding what Conflicts are but also has slight nuance in it that is important to understand.

Since Releases are always forked from the Master branch, then changes to the Master branch always taken precedence over changes in a Release. In effect, the Master branch is the "settled state" of the world and the Releases are always trying assert that their content should be allowed to merge back to Master.

If something changes in a Release, the Release has to finalize to prove that its content is mergeable. On the other hand, if something changes in the Master Branch, it's uncontestable. The Releases could find themselves in a state where their content is suddenly no longer mergeable due to no fault of their own. In essence, the carpet was pulled out from under their feet.

For this reason, Cloud CMS lets you do things like configure the Master Branch to ONLY be updatable via Releases. You can adjust this from the Manage Project > Releases page.

With this setting, the Master Branch will no longer be editable unless a Release merges the content as part of its release process.

Conflicts among Multiple Releases

In addition to detecting Conflicts that arise with the Master Branch, Cloud CMS will also detect Conflicts that arise between Releases.

Let's build on the example we had previously. Let's flip it around a bit.

On our Master branch, we have the same content item about the World Series:

But now, let's imagine we have two Releases:

• Wednesday Release
• Friday Release

On the Wednesday Release, we modify the title to Milwaukee Brewers play tomorrow in the World Series! - like this:

And on the Friday Release, we modify the title to Milwaukee Brewers win the World Series! - like this:

You might ask - why would we do this? Well, suppose the Brewers were playing on Thursday. We might want to prepare the content for a Wednesday edition of our web site (where we mention that the game is tomorrow). At the same time, concurrent with that, we might want to build a potential Friday edition that assumes the Brewers won.

Note that we might also prepare a concurrent Friday edition where we assume the Brewers lost.

At any rate, we now have two Releases where the title has different values.

Suppose we go to the Wednesday Release and Finalize and Schedule it. No problem. Nothing changed on Master and there are no other finalized Releases, so things lock in just fine.

The Wednesday Release is now finalized and locked in. In effect, by Finalizing and Scheduling, we've told Cloud CMS that we want the changes on the Wednesday Release to be the future state of things come Wednesday. Any other Releases that get introduced will have to be "in agreement" with the Wednesday Release before they can merge.

Let's see this in action.

Now that the Wednesday Release is locked in, go to the Friday Release and try to Finalize it.

You'll see a popup like this:

On the Overview Screen for the Friday Release, you'll see two interesting bits of information:

Finalization Impact - this identifies other Releases that could impact the Friday Release. In this case, the Wednesday Release has already been finalized and so it could "stand in the way" of the Friday Release finalizing. In the event that there is a change to the Friday Release that is incompatible with the Wednesday Release, a Conflict will be detected and raised.

Outgoing Conflicts - this lists any detected Conflicts. In this case, Cloud CMS found a Conflict with the Wednesday Release's version of this document. The title was changed in the Wednesday Release and it has a different and incompatible value with the value we gave it in the Friday Release.

You might now wonder how you should resolve this. Read on to the next section!

Ordering of Releases

Cloud CMS was designed to provide editorial teams with the ability to work on many Releases all at the same time. Some teams use this to break down "go live events" into discrete tasks. Others use this to manage multiple future states of their content. These futures are sometimes put into play and sometimes they are not - often depending on the outcome of external factors (such as sporting events or world news).

In the previous section, we considered a scenario with multiple Releases where the two Releases were in conflict with each other. We might be inclined to think that we have to now make changes to these Releases in order to get them to agree with each other.

Not so.

Consider that the Wednesday Release is already locked in. It's going to go live on Wednesday. However, the Friday Release is a bit unhappy at the moment because it is being prevented from locking in (i.e. finalizing) for Friday. It's being prevented because the Wednesday Release will have merged before it and, in doing so, it will have modified the Master branch to a state that the Friday Release isn't familiar with.

Cloud CMS detects this Conflict and asks you what you would like to do about it (from the perspective of the Friday Release).

If you click in the Friday Release and delve into the Conflicts, you'll see something like this:

Click on Resolve... and now consider the question from the perspective of the Friday Release. The Friday Release wants you to confirm for it what it should do regarding this title property when Friday comes.

Click on Keep My Version and then Save Resolutions to tell the Friday Release to keep on keeping on. It's all good. We know that the Wednesday Release is doing something funny and we approve of it. We want the Friday Release to use its own value come Friday. And we're sure of that.

Now go back to the Overview page and click Finalize and Schedule.

That's it. Friday is now scheduled:

You'll now see them show up on the Release Calendar as well.

Scheduling Content Availability

You can use Multiple Releases to Schedule the Availability of your Content. We can use one Release to merge the new content to the Master Branch. And we can use another release to remove it from the Master Branch at a later point in time.

Let's play with an example.

Suppose we had an empty Master Branch. We then create two Releases - Wednesday Release and Friday Release.

On the Wednesday Release, we can create a piece of content, like this:

We can then Finalize and Schedule the Wednesday Release. It's locked in.

Now we switch over to the Friday Release. We notice that the Friday Release is empty. This is because the new content was created on the Wednesday Release. We don't have it on the Friday Release.

Let's copy it over.

On the Friday Release page, click on Explore. You'll see a list of the Releases and Branches in the Project:

The Friday Release is the current release. It shows up as highlighted. Click on the radio button next to the Wednesday Release and the click on Selected... > Copy From Workspace.

The Copy From Workspace action will pop up and will show you the content that is available to be copied.

In this case, there's just one content item. It's the item we created in the Wednesday Release. Select it using the checkbox and then click on the Copy button at the bottom.

We've now copied the item into our Friday Release.

Next, in the Friday Release, go to the Content page. You'll see the copied item appear there.

Select the item and then click on Selected... > Delete Content Instance.

Delete the content instance. Once you've done that, go back to the Friday Release Overview page and try to Finalize and Schedule your Release.

Our expectation is that a Conflict will occur. The reason is because we deleted a content item on the Friday Release that exists on the Wednesday Release. The Conflict will display and will indicate the reason for the conflict (because our local copy of the content node was deleted):

Resolve the Conflict as in the previous section by Keeping the Local changes. And then Finalize and Schedule again.

That's all there is to it. You now have two Releases set up. The first one will merge the new content item to the Master Branch. And the second one will merge a deletion of the very same content, removing it from the Master Branch.