name: Continuous Integration  # Name of this workflow as shown in the Actions/CI UI

on:  # Section defining which events trigger this workflow
  push:  # Trigger when code is pushed
    branches:  # Branch patterns that should trigger this workflow on push
      - 'feature/**'  # Run CI for all branches under feature/ (e.g., feature/new-api)
      - 'bugfix/**'  # Run CI for all branches under bugfix/ (e.g., bugfix/fix-login)

  pull_request:  # Trigger when a pull request event occurs
    branches:  # Pull requests targeting these base branches will trigger this workflow
      - main  # Run CI for pull requests whose base (target) branch is main
    types:  # Specific pull request activity types that trigger this workflow
      - opened  # Trigger when a pull request is opened
      - reopened  # Trigger when a previously closed pull request is reopened
      - synchronize  # Trigger when new commits are pushed to the pull request source branch

  workflow_dispatch:  # Allow this workflow to be triggered manually from the UI
    inputs:  # Optional inputs for manual runs
      reason:  # Input describing why CI was triggered manually
        description: "Reason for manually running Continuous Integration"  # Help text for this input
        required: false  # This input is optional
        default: "manual-trigger"  # Default value when no explicit reason is provided

permissions:  # Default permissions for the CI token used in this workflow
  contents: read  # Allow reading repository contents (required for checking out code)
  # Add further permissions here if CI needs them (e.g., packages: read, issues: write, etc.)

jobs:  # Collection of jobs in this workflow
  validate:  # Job responsible for validating changes (build, tests, etc.)
    name: Validate and test changes  # Human-readable name for this job
    runs-on: ubuntu-latest  # Use the latest Ubuntu Linux runner image

    timeout-minutes: 20  # Fail the job automatically if it runs longer than 20 minutes

    concurrency:  # Prevent overlapping CI runs for the same ref
      group: ci-${{ gitea.ref_name }}-validate  # Group key: serialize CI runs per branch/tag name
      cancel-in-progress: true  # Cancel any in-progress job in this group when a new one starts

    steps:  # Ordered list of steps in this job
      - name: Checkout Code  # Step to fetch the repository contents
        uses: actions/checkout@v6  # Standard checkout action (Gitea-compatible)
        with:  # Options configuring the checkout behavior
          fetch-depth: 0  # Fetch full history so advanced git operations are possible if needed

      - name: Report Triggering Event and Branches  # Step to log which event and branches triggered CI
        shell: bash  # Explicitly use bash for this script
        run: |  # Begin multi-line bash script
          set -euo pipefail  # Enable strict mode: exit on error, unset var, or failed pipe

          EVENT_TYPE="${{ gitea.event_name }}"  # Capture the event type (push, pull_request, etc.)
          echo "Workflow triggered by event type: ${EVENT_TYPE}"  # Log the event type

          if [ "${EVENT_TYPE}" = "push" ]; then  # Branch for push events
            echo "Pushed to branch: ${{ gitea.ref_name }}"  # Log the branch name for push events
          elif [ "${EVENT_TYPE}" = "pull_request" ]; then  # Branch for pull request events
            echo "Pull request source branch (head_ref): ${{ gitea.head_ref }}"  # Log the PR source branch
            echo "Pull request target branch (base_ref): ${{ gitea.base_ref }}"  # Log the PR target branch
          else  # Branch for unexpected event types
            echo "Unexpected event type: ${EVENT_TYPE}"  # Log a warning for unknown events
          fi  # End of event-type conditional

      # - name: Restore Dependency Cache  # OPTIONAL: uncomment and configure for your language/toolchain
      #   uses: actions/cache@v4  # Cache action for speeding up dependency installation
      #   with:  # Cache configuration
      #     path: |  # Paths to cache (example: Node.js dependencies)
      #       node_modules
      #     key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}  # Cache key based on OS and lockfile
      #     restore-keys: |  # Fallback keys for partial cache hits
      #       deps-${{ runner.os }}-  # Broader prefix allowing reuse of older caches

      - name: Run Build and Tests  # Main CI step to build and test the project
        shell: bash  # Use bash shell for the build/test script
        env:  # Environment variables available to this step
          CI: "true"  # Conventional flag signaling that commands run in a CI environment
        run: |  # Begin multi-line bash script for build and tests
          set -euo pipefail  # Enforce strict error handling during build and tests

          echo "Building and testing the branch..."  # High-level log for build/test phase

          # --- Placeholder for actual build and test commands ---  # Marker for project-specific CI logic
          # Example for a Node.js project:  # Example showing a typical Node.js CI sequence
          #   npm ci  # Clean, reproducible install of dependencies using package-lock.json
          #   npm test  # Run unit tests
          #   npm run lint  # Run linting/static analysis
          # Example for a Go project:  # Example showing a typical Go CI sequence
          #   go test ./...  # Run all tests in all subpackages
          #   golangci-lint run  # Run Go linters via golangci-lint
          # ------------------------------------------------------  # End of placeholder examples

          echo "Build and tests completed successfully (assuming real commands are configured above)."  # Summary for successful CI run