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.

[object Object]

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.

[object Object]

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.

[object Object]

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.

[object Object]

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:

[object Object]

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:

[object Object]

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:

[object Object]

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:

[object Object]

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

conflict5.png

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.

conflict6.png

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.

conflict7.png

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.

conflict8.png

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.

conflict9.png

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:

[object Object]

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:

[object Object]

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

conflict12.png

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

conflict13.png

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:

conflict14.png

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.

[object Object]

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.

[object Object]

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:

[object Object]

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

  • Wednesday Release
  • Friday Release
[object Object]

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

[object Object]

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

[object Object]

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:

[object Object]

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

conflict46.png

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:

conflict47.png

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:

conflict48.png

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

conflict49.png

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:

conflict60.png

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:

conflict61.png

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.

conflict62.png

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

conflict63.png

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.

[object Object]

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):

conflict65.png

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.