monthly-version-tag.yaml

# Automated Monthly Release Versioning Workflow
# ============================================

# Purpose:
# - Automatically create consistent monthly version tags
# - Implement a calendar-based versioning strategy
# - Facilitate easy tracking of monthly releases

# Versioning Strategy:
# - Tag format: YYYY.MM.0 (e.g., 2024.01.0 for January 2024)
# - First digit: Full year
# - Second digit: Month (01-12)
# - Third digit: Patch version (starts at 0, allows for potential updates)

# Key Features:
# - Runs automatically on the first day of each month at 3:30 AM UTC
# - Can be manually triggered via workflow_dispatch
# - Uses GitHub Actions to generate tags programmatically
# - Provides a predictable and systematic versioning approach

# Prerequisites:
# - Repository configured with GitHub Actions
# - Permissions to create tags
# - Access to actions/checkout and tag creation actions

# Workflow Triggers:
# - Scheduled monthly run
# - Manual workflow dispatch
# - Callable from other workflows

# Actions Used:
# 1. actions/checkout@v4 - Checks out repository code
# 2. josStorer/get-current-time - Retrieves current timestamp
# 3. rickstaa/action-create-tag - Creates Git tags

# Example Generated Tags:
# - 2024.01.0 (January 2024 initial release)
# - 2024.02.0 (February 2024 initial release)
# - 2024.02.1 (Potential patch for February 2024)

# Workflow Configuration
# Create a new workflow file in `.github/workflows/monthly-version-tag.yml`:
#
#   ```yaml
# name: Tag Monthly Release
#
# on:
#   # Allow manual triggering of the workflow
#   workflow_dispatch:
#   # Schedule the workflow to run monthly
#   schedule:
#     # Runs at 03:30 UTC on the first day of every month
#     # Cron syntax: minute hour day-of-month month day-of-week
#     - cron: '30 3 1 * *'
#
# concurrency:
#   group: "monthly-release"
#   cancel-in-progress: false
#
# jobs:
#   monthly_release:
#     name: Tag Monthly Release
#     uses: openMF/mifos-mobile-github-actions/.github/workflows/monthly-version-tag.yaml@main
#     secrets: inherit
#   ```

# Workflow to automatically create monthly version tags
# This workflow runs on the first day of each month at 3:30 AM UTC
# It can also be triggered manually via workflow_dispatch
name: Tag Monthly Release

on:
  workflow_call:

jobs:
  tag:
    # Job to create a new version tag based on the current year and month
    # This helps track monthly releases in a calendar-based versioning scheme
    name: Tag Monthly Release
    runs-on: ubuntu-latest
    steps:
      # Step 1: Checkout the repository
      # This is required to perform any operations on the repository
      - uses: actions/checkout@v4

      # Step 2: Get current timestamp
      # This action provides formatted date/time outputs that we can use
      # for creating our version tag
      - name: Get Current Time
        uses: josStorer/get-current-time@v2.1.2
        id: current-time # This ID is used to reference the outputs in later steps

      # Step 3: Create the version tag
      # Creates a new tag in the format YYYY.MM.0 (e.g., 2024.01.0 for January 2024)
      # The .0 suffix allows for potential patch releases within the same month if needed
      - name: Bump Calendar Version
        uses: rickstaa/action-create-tag@v1.7.2
        with:
          # Combine year and month from current-time outputs to form the tag
          # Format: YYYY.MM.0 (year.month.patch)
          # The .0 suffix indicates this is the initial release for this month
          tag: ${{ steps.current-time.outputs.year }}.${{ steps.current-time.outputs.month }}.0