SharePoint Page Versioning (Major, Minor, Draft)

SharePoint page versioning can feel confusing, especially when you automate updates using C# and suddenly see errors like:

The file must be checked out before it can be updated
Page stuck in Draft even after update
Version conflicts after Update()

This article explains page versioning in very simple terms, with clear C# examples, so you know exactly what SharePoint is doing behind the scenes.

1. What Is a SharePoint Page, Really?

A modern SharePoint page (.aspx) is two things at the same time:

A file in the Site Pages library
A list item with metadata (Title, Category, Market, etc.)

Because of this, SharePoint applies:

File rules (checkout, publish)
List rules (versioning, approval)

Understanding this removes 80% of confusion.

2. Major vs Minor Versions

Version	Meaning
1.0	Published page (visible to everyone)
1.1	Draft version (not fully published)
2.0	Next published version

Important rule: "Any edit creates a draft (minor) version first."

Read version info in C#

var file = context.Web.GetFileByServerRelativeUrl(pageUrl);
context.Load(file, f => f.MajorVersion, f => f.MinorVersion);
await context.ExecuteQueryAsync();


string version = $"{file.MajorVersion}.{file.MinorVersion}";

3. Why Pages Become Draft After Metadata Update

When you update page metadata, SharePoint thinks: "This page changed, so it's now a draft."

Internally, it updates a hidden field called: _ModerationStatus

int status = (int)item["_ModerationStatus"];

4. Checkout: Why SharePoint Blocks Your Code

Most Site Pages libraries require checkout.

So SharePoint says: "You must check out the page before changing it."

If you don't, any update will fail.

Correct checkout code

context.Load(file, f => f.CheckOutType);
await context.ExecuteQueryAsync();
if (file.CheckOutType == CheckOutType.None)
{
    file.CheckOut();
    await context.ExecuteQueryAsync();
}

5. Why `item.Update()` Creates Draft Versions

item.Update(); - Always creates a draft version when the page is checked out.

That is normal SharePoint behavior, not a bug.

6. How to Publish a Page Properly

To make the page visible again:

Check in the page
Publish it

Correct publishing code

file.CheckIn("Metadata updated", CheckinType.MajorCheckIn);
await context.ExecuteQueryAsync();
file.Publish("Published after update");
await context.ExecuteQueryAsync();

This creates:

A new major version (for example, 2.0)
_ModerationStatus = Approved

7. Renaming a Page

Renaming a page means updating: FileLeafRef

This must be done while the page is checked out.

string newName = "Monthly-Report.aspx";
string folder = file.ServerRelativeUrl.Substring(0, file.ServerRelativeUrl.LastIndexOf("/"));
file.MoveTo($"{folder}/{newName}", MoveOperations.Overwrite);
await context.ExecuteQueryAsync();

8. Safe & Simple Pattern

// Load page
var file = context.Web.GetFileByServerRelativeUrl(pageUrl);
context.Load(file, f => f.CheckOutType, f => f.ListItemAllFields);
await context.ExecuteQueryAsync();

// Checkout
if (file.CheckOutType == CheckOutType.None)
{
file.CheckOut();
await context.ExecuteQueryAsync();
}

// Update metadata
var item = file.ListItemAllFields;
item["Title"] = "Updated Title";
item.Update();
await context.ExecuteQueryAsync();

// Publish
file.CheckIn("Updated metadata", CheckinType.MajorCheckIn);
await context.ExecuteQueryAsync();
file.Publish("Published");
await context.ExecuteQueryAsync();

Conclusion

SharePoint page versioning often feels complicated, but in reality it follows a very strict and predictable flow.

The confusion usually comes from forgetting that a modern page is both a file and a list item. Because of this, SharePoint enforces checkout, draft versions, approval, and publishing — even when you update something small like metadata.

If you are working with C# (CSOM, Azure Functions, background jobs), remember these key points:

Any update creates a draft (minor) version
Metadata updates do not automatically publish pages
Checkout is mandatory when required by the library
Only CheckIn + Publish create a major version

Once you follow the correct lifecycle:

Checkout → Update → CheckIn → Publish

SharePoint page automation becomes stable, predictable, and error-free.