Web Technology Development Basic Workshop

Instructor: Suriya Sonphu

Version Backend and Frontend Releases

Use Semantic Versioning to communicate what changed in the Todo API and Vue frontend, and to decide whether a release is a bug fix, a compatible feature, or a breaking change.

StandardSemVer 2.0.0
Backend.NET project version
Frontendpackage.json version
PracticeRelease notes
VERSIONING

Why versions matter

A version number is a short contract with the next developer, tester, or student who runs the project. It answers three practical questions:

  • Can I upgrade without changing my code?
  • Did this release only fix a bug, or did it add behavior?
  • Do the backend API and frontend application still match?

This workshop uses Semantic Versioning 2.0.0 for both the .NET backend and the Vue frontend.

SEMVER

Semantic Versioning in one page

A normal version has three numbers: MAJOR.MINOR.PATCH.

Part When to increase it Todo project example
MAJOR Backward-incompatible public API or app behavior. Rename isCompleted to done in API responses.
MINOR Backward-compatible feature. Add GET /api/todos?completed=true.
PATCH Backward-compatible bug fix. Fix edit validation while keeping the same API contract.

Use pre-release labels for builds that are not final: 1.1.0-alpha.1, 1.1.0-beta.1, or 1.1.0-rc.1. Use build metadata when you need traceable build information that does not change precedence: 1.1.0+20260912.

After a version is released, do not edit that released artifact in place. Make another change and release a new version.
BACKEND

Version the .NET API

For this workshop, the backend public API is the HTTP contract: routes, methods, status codes, authentication rules, and JSON DTO shapes documented by the Minimal API and OpenAPI output.

Add a version to backend/TodoApi/TodoApi.csproj when preparing a backend release: 

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <Version>1.0.0</Version>
</PropertyGroup>

Backend version decisions

Change Version bump Reason
Fix PUT /api/todos/{id} validation. PATCH The endpoint contract stays the same.
Add GET /api/todos/{id}. MINOR Existing clients still work.
Require a new claim for every Todo endpoint. MAJOR Existing clients must change their authentication flow.
Remove title from Todo responses. MAJOR The response shape breaks existing frontend code.
The workshop can start at 0.1.0 while the API is still being designed. Use 1.0.0 when the lab's API contract is stable enough for students to depend on.
FRONTEND

Version the Vue application

The frontend version lives in frontend/package.json. This repo already has: 

{
  "name": "ku-workshop-todo-frontend",
  "version": "1.0.0",
  "private": true
}

Even though the app is private and not published to npm, the version still helps identify which UI, API client, and dependency set was used in a workshop or deployment.

Frontend version decisions

Change Version bump Reason
Fix an edit button that did not submit the update. PATCH Same screen and API behavior, corrected implementation.
Add a completed/incomplete filter. MINOR New feature without removing existing behavior.
Change the app to require a different login response. MAJOR The frontend no longer works with the old backend contract.

Keep dependency ranges intentional. A patch update such as 1.20.0 to 1.20.1 should be low risk, but a major framework update should be tested with npm run build --prefix frontend and a browser CRUD check.

WORKFLOW

Recommended release workflow

  1. Decide the version bump from the actual behavior change.
  2. Update backend/TodoApi/TodoApi.csproj and/or frontend/package.json.
  3. Run the backend and frontend verification commands.
  4. Write release notes with breaking changes listed first.
  5. Create a Git tag such as backend-v1.0.0, frontend-v1.0.1, or v1.1.0 for a coordinated full-stack release. 
dotnet build backend/TodoApi/TodoApi.csproj
npm run build --prefix frontend
git tag v1.0.0
Use one shared tag, such as v1.2.0, when backend and frontend must be released together. Use component tags only when they can be deployed independently.
EXAMPLES

Workshop version examples

Scenario Backend Frontend Suggested release
Fix frontend edit only. No API change. 1.0.0 -> 1.0.1 frontend-v1.0.1
Add Todo priority to API and UI. 1.0.0 -> 1.1.0 1.0.0 -> 1.1.0 v1.1.0
Rename Todo response fields. 1.1.0 -> 2.0.0 1.1.0 -> 2.0.0 v2.0.0
CHECKLIST

Before tagging a release

  • The version bump matches the public behavior change.
  • Backend DTOs, endpoints, auth rules, and status codes are documented.
  • Frontend API client still matches the backend contract.
  • dotnet build backend/TodoApi/TodoApi.csproj passes.
  • npm run build --prefix frontend passes.
  • Release notes explain migration steps for any breaking change.