Skip to content

release_process.md

Latest commit

 

History

History
386 lines (282 loc) · 10.3 KB

release_process.md

File metadata and controls

386 lines (282 loc) · 10.3 KB

Objeck Language Release Process

Version: 2.1 (Automated) Last Updated: 2026-02-26

This document describes the fully automated release process for Objeck Language using GitHub Actions.

📋 Table of Contents

  1. Overview
  2. Prerequisites
  3. Quick Release Guide
  4. Detailed Workflow
  5. Troubleshooting
  6. Manual Fallback

Overview

The Objeck Language release process is now fully automated using GitHub Actions CI/CD pipelines. The entire process takes approximately 60 minutes and requires zero manual intervention after creating a git tag.

What's Automated

✅ Build Process

  • Windows x64/ARM64 (MSI + ZIP)
  • Linux x64/ARM64 (TGZ)
  • macOS ARM64 (TGZ)
  • LSP package (ZIP)

✅ Code Signing

  • Automated Windows MSI signing
  • Timestamped signatures (no password prompts)

✅ Distribution

  • GitHub Releases (automatic upload)
  • Sourceforge (automatic upload)

✅ Documentation

  • API documentation generation
  • Deployment to objeck.org

Time Comparison

Process Old (Manual) New (Automated) Time Saved
Total Time 8+ hours 60 minutes 87%
Manual Steps 15+ 1 (git tag) 93%
Platforms Built Locally All None 100%
Error Rate High Low ~90%

Prerequisites

One-Time Setup (Already Done)

The following GitHub Secrets must be configured in repository settings:

Secret Name Purpose Required
WINDOWS_CERT_BASE64 Windows code signing certificate ✅ Yes
WINDOWS_CERT_PASSWORD Certificate password ✅ Yes
SOURCEFORGE_SSH_KEY Sourceforge SFTP access Optional
SOURCEFORGE_USERNAME Sourceforge username Optional
OBJECK_ORG_SSH_KEY objeck.org deployment Optional
OBJECK_ORG_USER objeck.org SSH username Optional

Note: GITHUB_TOKEN is automatically provided by GitHub Actions.

Developer Requirements

  • Git command line tools
  • Write access to the repository
  • Ability to create and push tags

Quick Release Guide

Pre-Release Checklist

Before tagging, ensure the following are updated:

  1. Version string in core/shared/version.h (VER_NUM and VERSION_STRING)
  2. Release notes in README.md, docs/readme.txt, and docs/readme.html
  3. Download URLs in README.md Quick Start section
  4. Web playground version tag in programs/web-playground/frontend/index.html
  5. LSP repo (objeck-lsp) — update formatter for any new keywords, regenerate objk_apis.json
  6. Clean working tree — no uncommitted changes, .gitignore up to date

Creating a New Release

  1. Ensure your local repository is up to date:

    git checkout master
git pull origin master

  2. Create and push a version tag:

    # Format: vYYYY.M.P (e.g., v2026.2.1)
git tag v2026.2.1
git push origin v2026.2.1

  3. Wait for automation:

  4. Update the GitHub Release body with proper release notes (the auto-generated body is generic)

  5. Verify the release:

That's it! The entire release is now published.

Detailed Workflow

Step 1: Release Build (release-build.yml)

Trigger: Git tag matching v*.*.* (e.g., v2026.2.1)

What Happens:

  1. Version extraction from git tag
  2. Version file updates (automatic)
  3. Parallel platform builds:
    • Windows x64 (MSI + ZIP)
    • Windows ARM64 (MSI + ZIP)
    • Linux x64 (TGZ)
    • Linux ARM64 (TGZ)
    • macOS ARM64 (TGZ)
    • LSP package (ZIP)
  4. API documentation generation
  5. Artifact uploads (retained for 7 days)

Duration: ~45 minutes

Monitoring:

# View workflow status
gh run list --workflow=release-build.yml

# Watch live logs
gh run watch

Step 2: Release Publish (release-publish.yml)

Trigger: Automatic on successful Release Build completion (also supports manual dispatch)

What Happens:

  1. Download build artifacts
  2. Binary renaming with version numbers
  3. Code signing (Windows MSI files)
  4. GitHub Release creation:
    • Release notes generation
    • Binary uploads
    • Tag association
  5. Sourceforge upload (if configured)
  6. API documentation deployment (if configured)

Duration: ~15 minutes

Automatic Trigger: The publish workflow runs automatically when Release Build completes successfully. No manual intervention needed.

Manual Trigger (fallback):

# Get the run ID from the release build
RUN_ID=$(gh run list --workflow=release-build.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# Trigger publish workflow
gh workflow run release-publish.yml \
  -f version=2026.2.1 \
  -f run_id=$RUN_ID

Or use the GitHub Actions UI:

  1. Go to Actions → Release Publish
  2. Click Run workflow
  3. Enter version and run ID
  4. Click Run workflow

Post-Publish: Update the GitHub Release body with proper release notes matching the format of previous releases (see docs/readme.txt for content).

Troubleshooting

Build Failures

Problem: A platform build fails

Solution:

  1. Check the workflow logs: https://github.com/objeck/objeck-lang/actions
  2. Review the specific step that failed
  3. Common issues:
    • Dependency installation failure → Cached packages may be corrupted. Re-run workflow to refresh cache.
    • Compilation error → Fix code issues and push to master, then re-tag.
    • Test failure → Fix tests and re-push.

Re-running:

# Delete the tag
git tag -d v2026.2.1
git push origin :refs/tags/v2026.2.1

# Fix issues, commit, push

# Re-create tag
git tag v2026.2.1
git push origin v2026.2.1

Code Signing Issues

Problem: MSI signing fails

Solution:

  1. Verify WINDOWS_CERT_BASE64 and WINDOWS_CERT_PASSWORD secrets are set
  2. Check certificate expiration (certificates are valid for 1-3 years)
  3. Verify timestamp server is accessible (http://timestamp.sectigo.com)

Testing certificate locally:

# Decode certificate
$certBytes = [Convert]::FromBase64String("...")
[IO.File]::WriteAllBytes("test.pfx", $certBytes)

# Verify certificate
certutil -dump test.pfx

Upload Failures

Problem: Sourceforge or objeck.org upload fails

Solution:

  1. Verify SSH keys are valid and not expired
  2. Check network connectivity from GitHub Actions
  3. Verify remote directories exist and have write permissions
  4. Can be skipped using workflow inputs if needed

Skip uploads:

gh workflow run release-publish.yml \
  -f version=2026.2.1 \
  -f run_id=$RUN_ID \
  -f skip_sourceforge=true \
  -f skip_docs_deploy=true

Artifact Not Found

Problem: Release publish can't find build artifacts

Solution:

  1. Ensure the release build completed successfully
  2. Verify the run ID is correct
  3. Check artifact retention (7 days by default)

Finding the correct run ID:

gh run list --workflow=release-build.yml --limit 5

Manual Fallback

If the automated process fails completely, you can fall back to the manual process documented in release_process.txt (deprecated).

Emergency Manual Release

  1. Build locally:

    # Windows
cd core/release
deploy_windows.cmd x64 deploy
deploy_windows.cmd arm64 deploy

# Linux
./deploy_posix.sh x64 deploy
./deploy_posix.sh arm64 deploy

# macOS
./deploy_macos_arm64.sh deploy

  2. Sign MSI files:

    signtool sign /tr http://timestamp.sectigo.com /td sha256 /fd sha256 /a setup.msi

  3. Rename binaries:

    # Build rename tool
obc -src programs/deploy/util/deploy_rename.obs -lib misc
obr deploy_rename.obe <directory> <version>

  4. Upload manually:

Version Numbering

Objeck uses calendar versioning: YYYY.M.P

  • YYYY: Year (e.g., 2026)
  • M: Month (1-12, no leading zero)
  • P: Patch number (1, 2, 3, ...)

Examples:

  • 2026.2.1 - First release of February 2026
  • 2026.3.1 - First release of March 2026
  • 2026.12.1 - First release of December 2026

Git Tags: Always prefix with v: v2026.2.1

Continuous Integration

Every push to master triggers the CI build workflow (ci-build.yml), which:

  1. Builds all 5 platforms in parallel
  2. Runs test suites
  3. Runs regression tests
  4. Generates build artifacts (retained 7 days)

Purpose: Catch issues early before release

Monitoring:

  • Status badges on README
  • GitHub Actions dashboard
  • Email notifications (if configured)

Release Checklist

Use this checklist for each release:

  • All tests passing on master (CI green)
  • Version number updated in core/shared/version.h
  • Release notes updated in README.md, docs/readme.txt, docs/readme.html
  • Download URLs in README.md point to new version
  • Web playground version tag updated
  • LSP repo updated (new keywords, regenerated API JSON)
  • Git tag created and pushed (git tag vX.Y.Z && git push origin vX.Y.Z)
  • Release build workflow completed successfully
  • Release publish workflow completed (auto-triggered)
  • GitHub Release body updated with proper release notes
  • GitHub Release verified with all platform assets
  • Sourceforge upload verified (if enabled)
  • API docs deployed (if enabled)
  • Downloads tested on at least one platform

Support

Changelog

Version Date Changes
2.1 2026-02-26 Added pre-release checklist, clarified auto-trigger, LSP update step
2.0 2026-02-10 Fully automated CI/CD release process
1.0 2024-xx-xx Manual release process