From f22b159dceb45f9c9aa529eb1b98579dbf5cd5bf Mon Sep 17 00:00:00 2001 From: Gyan Ponnappa <129504209+Darkeye14@users.noreply.github.com> Date: Wed, 4 Dec 2024 20:20:31 +0530 Subject: [PATCH] workflow documentation (#1828) * pipeline documentation * pipeline documentation buildAndPublishOnPlatforms.yaml * pipeline documentation make_site.yaml * workflow documentation buildAndPublishOnPlatforms.yaml * workflow documentation make_site.yaml --- .../build_and_publish_on_platforms.yaml | 345 +++++++++++++++--- .github/workflows/make_site.yaml | 21 +- 2 files changed, 311 insertions(+), 55 deletions(-) diff --git a/.github/workflows/build_and_publish_on_platforms.yaml b/.github/workflows/build_and_publish_on_platforms.yaml index 627683d98..c68300279 100644 --- a/.github/workflows/build_and_publish_on_platforms.yaml +++ b/.github/workflows/build_and_publish_on_platforms.yaml @@ -1,12 +1,16 @@ -# Workflow name indicating its purpose +# This workflow file defines a comprehensive build and release pipeline for a +# multi-platform application. It automates the process of building, testing, and deploying the +# application to various platforms, including Android, iOS, Desktop (Windows, macOS, Linux), and Web. name: Multi-Platform App Build and Publish # Trigger configuration +# This keyword specifies the events that trigger the workflow. on: # Manual trigger through GitHub Actions UI with configurable inputs workflow_dispatch: +# This section defines the configurable inputs for the workflow. inputs: - # Release channel selection (internal/beta) + # A choice input for selecting the release type (internal or beta), defaulting to internal. release_type: type: choice options: @@ -16,30 +20,34 @@ on: description: Release Type # Toggle for Android Play Store publishing + # : A boolean input to control Android app publishing to the Play Store, defaulting to false. publish_android: type: boolean default: false description: Publish Android App On Play Store # Toggle for iOS App Store publishing + # A boolean input to control iOS app publishing to the App Store, defaulting to false. publish_ios: type: boolean default: false description: Publish iOS App On App Store # Toggle for Desktop app publishing (Windows/macOS/Linux) + # A boolean input to control desktop app publishing, defaulting to false. publish_desktop: type: boolean default: false description: Publish Desktop Apps On App Store # Toggle for Web app deployment + # A boolean input to control web app publishing, defaulting to true. publish_web: type: boolean default: true description: Publish Web App - # Toggle for iOS build process + # A boolean input to control the iOS build process, defaulting to false. # Separated from publishing to allow building without deployment build_ios: type: boolean @@ -47,32 +55,40 @@ on: description: Build iOS App # Repository-level permissions configuration +# This section defines the permissions required by the workflow. permissions: - # Grant read/write access to repository contents for deployment + # Grants the workflow write access to the repository contents, necessary for deployment tasks. contents: write # Concurrency management configuration # Controls how multiple workflow runs are handled concurrency: - # Uses "pages" group to coordinate with GitHub Pages deployments + # Uses "pages" group to coordinate with GitHub Pages deployments, preventing conflicts group: "pages" - # When false, new runs are queued instead of cancelling running ones + # When false, new runs (workflow) are queued instead of cancelling running ones # This ensures deployment stability and ordered releases cancel-in-progress: false # Job definitions for different platforms +# This section defines the different jobs that make up the workflow. jobs: # Android Build Job # Handles compilation and APK generation for Android platform build_android: + # Sets the job name to "Build Android Application." name: Build Android Application + # Specifies that the job will run on an ubuntu-latest runner. runs-on: ubuntu-latest + # This section defines the individual steps within the job. steps: # Check out repository code + # This step checks out the repository code using the actions/checkout@v4 action. - name: Checkout uses: actions/checkout@v4 # Setup Java development environment + # This step sets up the Java development environment using the actions/setup-java@v4.2.2 action + # with Temurin distribution and Java version 17. - name: Set up JDK 17 uses: actions/setup-java@v4.2.2 with: @@ -80,10 +96,13 @@ jobs: java-version: '17' # Configure Gradle build tool + # This step configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action. - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 # Cache Gradle dependencies to speed up builds + # This step caches Gradle dependencies using the actions/cache@v3 action, + # specifying the paths to cache and the cache key. - uses: actions/cache@v3 with: path: | @@ -93,6 +112,7 @@ jobs: key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }} # Decrypt and prepare required secrets for signing + # This step uses a custom action to decrypt and prepare secrets for signing the Android app. - uses: ./.github/actions/inflate-secrets name: Inflate Secrets with: @@ -102,6 +122,8 @@ jobs: firebase-creds: ${{ secrets.FIREBASECREDS }} # Build signed release APK + # This step builds the signed release APK using Gradle, setting environment variables for + # keystore details and version code. - name: Build Release env: KEYSTORE_PASSWORD: ${{ secrets.ORIGINAL_KEYSTORE_FILE_PASSWORD }} @@ -112,6 +134,9 @@ jobs: ./gradlew :mifospay-android:assembleRelease # Save built APKs as artifacts + # This step uploads the built Android APKs as artifacts using the actions/upload-artifact@v4 + # action, specifying the artifact name, retention days, compression level, + # and paths to the APKs. - name: Upload Android Artifact uses: actions/upload-artifact@v4 with: @@ -125,15 +150,23 @@ jobs: # Firebase Distribution Job for Android # Handles deployment to Firebase App Distribution for testing publish_android_on_firebase: + # Sets the name of the job. name: Deploy Android App On Firebase + # Specifies that this job depends on the successful completion of the + # build_android and generate_release_info jobs. needs: [ build_android, generate_release_info ] + # Indicates that this job will run on a macOS runner and its latest version. runs-on: macos-latest + # Defines the sequence of steps to be executed within the job. steps: # Basic setup steps + # Checks out the repository code using the actions/checkout@v4 action. - name: Checkout uses: actions/checkout@v4 # Setup Java environment + # Sets up the Java development environment using the actions/setup-java@v4.2.2 action with + # Temurin distribution and Java version 17. - name: Set up JDK 17 uses: actions/setup-java@v4.2.2 with: @@ -141,16 +174,22 @@ jobs: java-version: '17' # Configure Gradle + # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action. - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 # Setup Ruby for Fastlane automation + # Sets up the Ruby environment using the ruby/setup-ruby@a2bbe... action and + # enables bundler caching. - name: Configure Ruby uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0 with: bundler-cache: true - # Install Fastlane and required plugins for deployment automation + # Installs Fastlane and the required plugins (firebase_app_distribution and + # increment_build_number) using RubyGems and Bundler. It specifies a specific version of + # Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better + # performance and resilience. - name: Install Fastlane run: | gem install bundler:2.2.27 @@ -158,61 +197,94 @@ jobs: bundle exec fastlane add_plugin firebase_app_distribution bundle exec fastlane add_plugin increment_build_number - # Prepare necessary secrets + # This step utilizes a custom action located at .github/actions/inflate-secrets within the + # repository. This action is likely responsible for decrypting or preparing secrets needed + # for the deployment process. - uses: ./.github/actions/inflate-secrets + # Sets the name of the step for clarity in the workflow logs. name: Inflate Secrets + # Provides input values to the custom action. with: + #Passes the ORIGINAL_KEYSTORE_FILE secret to the action, likely containing + # the Android keystore file. keystore: ${{ secrets.ORIGINAL_KEYSTORE_FILE }} + # Passes the GOOGLESERVICES secret, probably containing the Google Services + # JSON file for Firebase configuration. google-services: ${{ secrets.GOOGLESERVICES }} + # Passes the PLAYSTORECREDS secret, potentially containing credentials for + # Play Store interaction. playstore-creds: ${{ secrets.PLAYSTORECREDS }} + # Passes the FIREBASECREDS secret, likely containing Firebase service account credentials firebase-creds: ${{ secrets.FIREBASECREDS }} # Retrieve built Android artifacts + # Sets the name of the step. - name: Download Android Artifact + #Utilizes the actions/download-artifact@v4 action to download previously uploaded artifacts uses: actions/download-artifact@v4 + # Configures the download. with: + # Specifies the name of the artifact to download + #(which was likely uploaded in the build_android job). name: android-app + # Defines the local directory where the downloaded artifact will be stored. path: ./android-artifacts # Debug: List downloaded artifacts - name: List downloaded artifacts + # Executes a shell command. + # This command lists the contents of the android-artifacts directory recursively, + # which helps in debugging and verifying the downloaded artifact. run: | ls -R ./android-artifacts # Get changelog for Firebase distribution - name: Download Beta Changelog + # Uses the actions/download-artifact@v4 action to download the changelog artifact. uses: actions/download-artifact@v4 + #Configures the download. with: + # Specifies the name of the changelog artifact to download. name: beta-changelog # Organize files for Firebase deployment - name: Move APK to build directory - run: | + run: | #Executes shell commands. + # Creates the necessary directory structure for the APK if it doesn't exist. mkdir -p ./mifospay-android/build/outputs/apk/prod/release/ + # Moves the downloaded release APK to the designated build output directory. mv ./android-artifacts/prod/release/mifospay-android-prod-release.apk ./mifospay-android/build/outputs/apk/prod/release/ + #Moves the downloaded changelog file to the build output directory. mv ./changelogBeta ./mifospay-android/build/outputs/ - # Deploy to Firebase App Distribution - name: ☁️ Deploy to Firebase + # Sets environment variables for the step. env: + #Sets the VERSION_CODE environment variable to the value generated in the generate_release_info job. VERSION_CODE: ${{ needs.generate_release_info.outputs.version_code }} + #Executes the Fastlane lane android deploy_on_firebase to deploy the Android app to Firebase App Distribution. run: bundle exec fastlane android deploy_on_firebase - # Play Store Publishing Job - # Handles deployment to Google Play Store + #This defines the job for publishing the Android app to the Google Play Store. publish_android_on_playstore: name: Publish Android App On Play Store +#Specifies that this job depends on the successful completion of the build_android and generate_release_info jobs. needs: [ build_android, generate_release_info ] + # This job will only run if the publish_android input is set to true when the workflow is triggered. if: inputs.publish_android + # Indicates that this job will run on a macOS runner. runs-on: macos-latest + #Defines the sequence of steps to be executed within the job. steps: - # Checkout with full history for versioning + #Checks out the repository code using the actions/checkout@v4 action. - uses: actions/checkout@v4 + # Configures the checkout process. with: + #Fetches the complete commit history, which might be necessary for versioning or release notes generation. fetch-depth: 0 - # Setup Java environment + # Sets up the Java development environment using the actions/setup-java@v4.2.2 action with Temurin distribution and Java version 17. - name: Set up JDK 17 uses: actions/setup-java@v4.2.2 with: @@ -220,12 +292,16 @@ jobs: java-version: '17' # Setup Ruby for Fastlane + #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action and enables bundler caching. - name: Configure Ruby uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0 with: bundler-cache: true # Install Fastlane and plugins for Play Store deployment + #Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using + #RubyGems and Bundler. It specifies a specific version of Bundler (2.2.27) and configures bundle installation with + # 4 jobs and 3 retries for better performance and resilience. - name: Install Fastlane run: | gem install bundler:2.2.27 @@ -234,63 +310,88 @@ jobs: bundle exec fastlane add_plugin increment_build_number # Setup Gradle build tool + # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action. - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 # Prepare necessary secrets + #This step utilizes a custom action located at .github/actions/inflate-secrets within the repository. + #This action is likely responsible for decrypting or preparing secrets needed for the deployment process. - uses: ./.github/actions/inflate-secrets + #Sets the name of the step for clarity in the workflow logs. name: Inflate Secrets + # Provides input values to the custom action. with: + # Passes the UPLOAD_KEYSTORE_FILE secret to the action, likely containing the Android keystore file for uploading to the Play Store. keystore: ${{ secrets.UPLOAD_KEYSTORE_FILE }} + #Passes the GOOGLESERVICES secret, probably containing the Google Services JSON file for Firebase configuration. google-services: ${{ secrets.GOOGLESERVICES }} + #Passes the PLAYSTORECREDS secret, potentially containing credentials for Play Store interaction. playstore-creds: ${{ secrets.PLAYSTORECREDS }} + # Passes the FIREBASECREDS secret, likely containing Firebase service account credentials. firebase-creds: ${{ secrets.FIREBASECREDS }} # Build Android App Bundle for Play Store - name: Build Release env: + #Sets the KEYSTORE_PASSWORD environment variable to the value stored in the UPLOAD_KEYSTORE_FILE_PASSWORD secret. KEYSTORE_PASSWORD: ${{ secrets.UPLOAD_KEYSTORE_FILE_PASSWORD }} + #Sets the KEYSTORE_ALIAS environment variable to the value stored in the UPLOAD_KEYSTORE_ALIAS secret. KEYSTORE_ALIAS: ${{ secrets.UPLOAD_KEYSTORE_ALIAS }} + #Sets the KEYSTORE_ALIAS_PASSWORD environment variable to the value stored in the UPLOAD_KEYSTORE_ALIAS_PASSWORD secret. KEYSTORE_ALIAS_PASSWORD: ${{ secrets.UPLOAD_KEYSTORE_ALIAS_PASSWORD }} + #Sets the VERSION_CODE environment variable to the value generated in the generate_release_info job. VERSION_CODE: ${{ needs.generate_release_info.outputs.version_code }} - run: | + run: | # Executes a shell command. + #This command uses Gradle to build the Android App Bundle (AAB) for release, targeting the mifospay-android module. ./gradlew :mifospay-android:bundleRelease # Save AAB files as artifacts - name: Archive Build + #Utilizes the actions/upload-artifact@v4 action to upload the built AAB as an artifact. uses: actions/upload-artifact@v4 - with: + with: #Configures the upload. name: release-aabs + #Defines the path to the AAB file, using a wildcard to match any AAB files in any subdirectory. path: ./**/*.aab # Deploy to Play Store Internal testing track - name: Deploy to Playstore Internal + # Executes the Fastlane lane deploy_internal to deploy the AAB to the Play Store's internal testing track. run: bundle exec fastlane deploy_internal # Promote to beta if specified - name: Promote Internal to Beta + #This step will only run if the release_type input provided when triggering the workflow is set to beta. if: github.event.inputs.release_type == 'beta' + # Executes the Fastlane lane promote_to_beta to promote the release from the internal testing track to the beta testing track on the Play Store. run: bundle exec fastlane promote_to_beta # iOS Build Job # Handles compilation and IPA generation for iOS platform build_ios: name: Build iOS App + #Indicates that this job will run on a macOS runner, which is required for building iOS apps. runs-on: macos-latest steps: + # Checks out the repository code using the actions/checkout@v4 action. - uses: actions/checkout@v4 + #Sets up the Java development environment using the actions/setup-java@v4 action. This might be needed for some dependencies or build tools used in the iOS project. - uses: actions/setup-java@v4 - with: + with: #Configures the Java setup. java-version: 17 - distribution: 'temurin' + distribution: 'temurin' # Uses the Temurin distribution of Java. # Setup Ruby for Fastlane + #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action and enables bundler caching. - name: Configure Ruby uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0 with: bundler-cache: true # Install Fastlane and plugins for iOS automation + # Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using RubyGems and Bundler. + # It specifies a specific version of Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better performance and resilience. - name: Install Fastlane run: | gem install bundler:2.2.27 @@ -300,39 +401,56 @@ jobs: # Build iOS app if enabled + # This step builds the iOS app using Fastlane. - name: Build iOS App + #This step will only run if the build_ios input is set to true when the workflow is triggered. if: inputs.build_ios + # Executes the Fastlane lane ios build_ios to build the iOS app. run: bundle exec fastlane ios build_ios # Save IPA as artifact + #This step uploads the built iOS app (IPA file) as an artifact. - name: Upload iOS Artifact + #This step will only run if the build_ios input is set to true when the workflow is triggered. if: inputs.build_ios + # Utilizes the actions/upload-artifact@v4 action to upload the artifact. uses: actions/upload-artifact@v4 - with: + with: # Configures the upload. name: ios-app - retention-days: 1 - compression-level: 9 + retention-days: 1 # Sets the retention period for the artifact to 1 day. + compression-level: 9 # Uses the highest compression level for the artifact. + #Defines the path to the IPA file to be uploaded. I hope this detailed explanation helps you with your documentation. + #Let me know if you have any other questions or need further assistance with other parts of the workflow file. path: mifospay-ios/mifospay-ios-app.ipa # Firebase Distribution Job for iOS # Handles deployment to Firebase App Distribution for iOS testing publish_ios_app_to_firebase: name: Publish iOS App On Firebase + #This job will only run if the publish_ios input is set to true when the workflow is triggered. if: inputs.publish_ios + #Specifies that this job depends on the successful completion of the build_ios and generate_release_info jobs. needs: [ build_ios, generate_release_info ] + # Indicates that this job will run on a macOS runner, which is required for interacting with iOS build artifacts and tools. runs-on: macos-latest - permissions: + permissions: # Defines the permissions required by this job. + #Grants the job write access to the repository contents, which might be necessary for uploading artifacts or modifying files. contents: write - steps: + steps: # Defines the sequence of steps to be executed within the job. + #Checks out the repository code using the actions/checkout@v4 action. This is a common first step in most workflows + #to ensure the job has access to the project's files. - uses: actions/checkout@v4 # Setup Ruby for Fastlane + #Sets up the Ruby environment using the ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc action + #and enables bundler caching. This is likely needed because Fastlane, a popular mobile deployment tool, is written in Ruby. - name: Configure Ruby uses: ruby/setup-ruby@a2bbe5b1b236842c1cb7dd11e8e3b51e0a616acc # v1.202.0 with: bundler-cache: true - # Install Fastlane and plugins + # Installs Fastlane and the required plugins (firebase_app_distribution and increment_build_number) using RubyGems and Bundler. + # It specifies a specific version of Bundler (2.2.27) and configures bundle installation with 4 jobs and 3 retries for better performance and resilience. - name: Install Fastlane run: | gem install bundler:2.2.27 @@ -342,51 +460,79 @@ jobs: # Get iOS app artifact + # Downloads the previously built iOS app artifact (IPA file) using the actions/download-artifact@v4 action. - name: Download iOS App uses: actions/download-artifact@v4 + #Specifies the name of the artifact to download, which was likely uploaded in the build_ios job. with: name: ios-app # Get changelog for Firebase distribution + # Downloads the changelog artifact, presumably for including it with the Firebase App Distribution release. - name: Download Beta Changelog uses: actions/download-artifact@v4 + # pecifies the name of the changelog artifact to download. with: name: beta-changelog # Organize files for Firebase deployment + #Sets the name of the step. Although the name mentions "APK," it's actually moving the iOS IPA file and the changelog. - name: Move APK to build directory + #Moves any IPA file in the current directory to the mifospay-ios directory. + #This is likely done to place the IPA file in the expected location for the Fastlane deployment lane. run: | mv *.ipa ./mifospay-ios/ + #Moves the changelogBeta file (presumably the downloaded changelog) to the mifospay-android/build/outputs/ directory. + #This might be a mistake, as it's placing the iOS changelog in the Android build output directory. + #It's possible this line should be adjusted to place the changelog in a more appropriate location for the iOS deployment. mv changelogBeta ./mifospay-android/build/outputs/ # Deploy to Firebase App Distribution - name: Upload iOS App to Firebase Distribution + #Executes the Fastlane lane ios deploy_on_firebase to deploy the iOS app to Firebase App Distribution. + #This lane likely handles the authentication, upload, and distribution settings for Firebase. run: bundle exec fastlane ios deploy_on_firebase # Debug: Show git status - name: Print `git status` + # Executes the git status command. This is a debugging step to show the current state of the Git repository within the workflow environment. + #It can help identify any unexpected changes or issues with file operations. run: git status # App Center Publishing Job for iOS # Handles deployment to App Center for iOS distribution publish_ios_app_to_app_center: + #Specifies that this job depends on the successful completion of the build_ios and generate_release_info jobs. + #This ensures that the iOS app is built and the release information is generated before attempting to publish to App Center. needs: [ build_ios, generate_release_info ] + #Sets the name of the job, which will be displayed in the workflow logs. name: Publish iOS App On App Center + #This job will only run if the publish_ios input is set to true when the workflow is triggered. + #This allows you to control whether or not the app is published to App Center based on the workflow input. if: inputs.publish_ios + #Indicates that this job will run on a macOS runner, which is required for interacting with iOS build artifacts and tools. runs-on: macos-latest + # Checks out the repository code using the actions/checkout@v4 action. + #This is a common first step in most workflows to ensure the job has access to the project's files. steps: + #Checks out the repository code using the actions/checkout@v4 action. + #This is a common first step in most workflows to ensure the job has access to the project's files. - uses: actions/checkout@v4 # Get iOS app artifact + # Downloads the previously built iOS app artifact (IPA file) using the actions/download-artifact@v4 action. - name: Download iOS Artifact uses: actions/download-artifact@v4 with: name: ios-app # Get changelog for App Center + #Downloads the changelog artifact, presumably for including it with the App Center release. - name: Download Changelog uses: actions/download-artifact@v4 + #Specifies the name of the changelog artifact to download. This suggests that the changelog is generated + #using a tool or action that produces an artifact named "git-changelog." with: name: git-changelog @@ -394,57 +540,79 @@ jobs: # Desktop Build Job # Handles compilation for Windows, macOS, and Linux platforms + # This defines the job for building the desktop application. build_desktop: name: Build Desktop App + # Defines the build strategy for this job. strategy: + # Specifies a matrix build, which allows the job to run multiple times with different configurations. matrix: + # Defines the operating systems to build the desktop app for (Ubuntu, macOS, and Windows). os: [ ubuntu-latest, macos-latest, windows-latest ] + #Specifies that the job will run on the operating system defined in the matrix. runs-on: ${{ matrix.os }} - steps: + steps: # Defines the sequence of steps to be executed within the job. + #Checks out the repository code using the actions/checkout@v4 action. - uses: actions/checkout@v4 + #Sets up the Java development environment using the actions/setup-java@v4 action. - uses: actions/setup-java@v4 with: java-version: 17 distribution: 'temurin' # Setup Gradle build tool + #Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action. - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 # Build desktop app for current OS + #This step builds the desktop app using Gradle. - name: Build Desktop App + #Sets environment variables for the step. These variables are likely used for code signing or notarization on macOS. env: - NOTARIZATION_APPLE_ID: ${{ secrets.NOTARIZATION_APPLE_ID }} - NOTARIZATION_PASSWORD: ${{ secrets.NOTARIZATION_PASSWORD }} - NOTARIZATION_TEAM_ID: ${{ secrets.NOTARIZATION_TEAM_ID }} + NOTARIZATION_APPLE_ID: ${{ secrets.NOTARIZATION_APPLE_ID }} #Sets the Apple ID for notarization. + NOTARIZATION_PASSWORD: ${{ secrets.NOTARIZATION_PASSWORD }} #Sets the password for notarization. + NOTARIZATION_TEAM_ID: ${{ secrets.NOTARIZATION_TEAM_ID }} #Sets the team ID for notarization. + #Executes the Gradle task packageReleaseDistributionForCurrentOS to build the desktop app for the current operating system. run: ./gradlew packageReleaseDistributionForCurrentOS # Save Windows artifacts (EXE and MSI) - name: Upload Windows Apps + # This step will only run if the current operating system in the matrix is Windows. if: matrix.os == 'windows-latest' + # Utilizes the actions/upload-artifact@v4 action to upload the artifacts. uses: actions/upload-artifact@v4 with: - name: desktop-app-${{ matrix.os }} - retention-days: 1 - compression-level: 9 + name: desktop-app-${{ matrix.os }} #Specifies the name of the artifact, including the operating system. + retention-days: 1 #Sets the retention period for the artifact to 1 day. + compression-level: 9 # Uses the highest compression level for the artifact. + #Defines the paths to the EXE and MSI files to be uploaded. path: | ./mifospay-desktop/build/compose/binaries/main-release/exe/*.exe ./mifospay-desktop/build/compose/binaries/main-release/msi/*.msi # Save Linux artifact (DEB) + # This step uploads the built Linux app artifact (DEB file). - name: Upload Linux App + # This step will only run if the current operating system in the matrix is Ubuntu. if: matrix.os == 'ubuntu-latest' + #Utilizes the actions/upload-artifact@v4 action to upload the artifact. uses: actions/upload-artifact@v4 - with: + with: # Configures the upload, similar to the Windows upload step. name: desktop-app-${{ matrix.os }} retention-days: 1 compression-level: 9 path: './mifospay-desktop/build/compose/binaries/main-release/deb/*.deb' # Save macOS artifact (DMG) + #This step uploads the built macOS app artifact (DMG file). - name: Upload MacOS App + #This step will only run if the current operating system in the matrix is macOS. if: matrix.os == 'macos-latest' + # Utilizes the actions/upload-artifact@v4 action to upload the artifact. uses: actions/upload-artifact@v4 + #Configures the upload, similar to the Windows and Linux upload steps. I hope this detailed explanation helps you with your documentation. + #Let me know if you have any other questions or need further assistance with other parts of the workflow file. with: name: desktop-app-${{ matrix.os }} retention-days: 1 @@ -452,24 +620,37 @@ jobs: path: './mifospay-desktop/build/compose/binaries/main-release/dmg/*.dmg' # Desktop Publishing Job - # Handles publishing desktop apps to various stores + #This defines the job for publishing the desktop application to various stores. publish_desktop: name: Publish Desktop App + #Specifies that this job depends on the successful completion of the build_desktop job. + #This ensures that the desktop app is built before attempting to publish it. needs: [ build_desktop ] + # This job will only run if the publish_desktop input is set to true when the workflow is triggered. + #This allows you to control whether or not the app is published based on the workflow input. if: inputs.publish_desktop + #Indicates that this job will run on an Ubuntu runner. runs-on: ubuntu-latest + #Checks out the repository code using the actions/checkout@v4 action. + #This is a common first step in most workflows to ensure the job has access to the project's files. steps: - uses: actions/checkout@v4 # Get all desktop artifacts + #Downloads all the desktop app artifacts that were uploaded in the build_desktop job. - name: Download Desktop Artifacts + # Utilizes the actions/download-artifact@v4 action to download the artifacts. uses: actions/download-artifact@v4 - with: + with: #Configures the download. + # Specifies a pattern to match the artifact names. This will download all artifacts whose names start with "desktop-app-". pattern: desktop-app-* + #Defines the local directory where the downloaded artifacts will be stored. path: desktop-apps # TODO: Implement desktop store publishing # Debug: Show git status + #Executes the git status` command. This is likely a debugging step to show the current state of the Git repository within the workflow environment. + #It can help identify any unexpected changes or issues with file operations. - name: Print `git status` run: git status @@ -477,163 +658,225 @@ jobs: # Handles compilation of web application using Kotlin/JS build_web: name: Build Web Application - runs-on: windows-latest - steps: + runs-on: windows-latest #Indicates that this job will run on a Windows runner. + steps: #Defines the sequence of steps to be executed within the job. + #Checks out the repository code using the actions/checkout@v4 action. - uses: actions/checkout@v4 # Setup Java environment + #Sets up the Java development environment using the actions/setup-java@v4 action. - uses: actions/setup-java@v4 with: - distribution: 'zulu' + distribution: 'zulu' # Uses the Zulu distribution of Java. java-version: 17 # Cache Gradle dependencies + #Caches Gradle dependencies to speed up subsequent builds. - uses: actions/cache@v3 with: - path: | + path: | #Specifies the paths to cache (Gradle caches and Konan cache). ~/.gradle/caches ~/.gradle/wrapper ~/.konan + #Defines the cache key based on the runner OS and the hash of Gradle files. key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }} # Build web app using Kotlin/JS - name: Build Web(JS) App + #Executes the Gradle task jsBrowserDistribution to build the web app. + #This task likely produces the production-ready JavaScript files for the web application. run: ./gradlew jsBrowserDistribution # Save web app as artifact + #This step uploads the built web application as an artifact. - name: Upload Web Artifact + #Utilizes the actions/upload-artifact@v4 action to upload the artifact. uses: actions/upload-artifact@v4 - with: + with: #Configures the upload. name: web-app + #Defines the path to the built web app files to be uploaded. This path suggests that the web app is built using + #Kotlin/JS and the output is placed in the productionExecutable directory. I hope this detailed explanation helps you with your documentation. + #Let me know if you have any other questions or need further assistance with other parts of the workflow file. path: './mifospay-web/build/dist/js/productionExecutable' # Web Publishing Job # Handles deployment to GitHub Pages publish_web: name: Publish Web App + #Specifies that this job depends on the successful completion of the build_web job. This ensures that the web app is built before attempting to publish it. needs: [ build_web ] + # This job will only run if the publish_web input is set to true when the workflow is triggered. + #This allows you to control whether or not the web app is published based on the workflow input. if: inputs.publish_web - runs-on: ubuntu-latest + runs-on: ubuntu-latest # Indicates that this job will run on an Ubuntu runner. environment: + #Sets the environment name to "github-pages," indicating that this job deploys to GitHub Pages. name: github-pages + # Sets the environment URL to the page URL generated by the deployment step (which is defined later in the job). url: ${{ steps.deployment.outputs.page_url }} permissions: + #Grants the job write access to the GitHub OIDC (OpenID Connect) token. + #This is needed for authenticating with GitHub Pages. id-token: write - pages: write + pages: write #Grants the job write access to the GitHub Pages deployment. steps: + #Checks out the repository code using the actions/checkout@v4 action. - uses: actions/checkout@v4 + # Sets up the Java development environment using the actions/setup-java@v4 action. + #This might be needed for some dependencies or build tools used in the web app project. - uses: actions/setup-java@v4 with: distribution: 'zulu' java-version: 17 # Get web app artifact + # Downloads the previously built web app artifact using the actions/download-artifact@v4 action. - name: Download Web Artifact uses: actions/download-artifact@v4 with: + # Specifies the name of the artifact to download, which was likely uploaded in the build_web job. name: web-app + # Defines the local directory where the downloaded artifact will be stored. path: ./web-app-content # Configure GitHub Pages + #Configures GitHub Pages for the deployment using the actions/configure-pages@v5 action. + #This action sets up the necessary environment and settings for deploying to GitHub Pages. - name: Setup Pages uses: actions/configure-pages@v5 # Upload web app to GitHub Pages + #Uploads the web app content as an artifact to GitHub Pages using the actions/upload-pages-artifact@v3 action. - name: Upload static files as artifact uses: actions/upload-pages-artifact@v3 with: - path: './web-app-content' + path: './web-app-content' # Specifies the path to the web app content to be uploaded. # Deploy to GitHub Pages + # Deploys the web app to GitHub Pages using the actions/deploy-pages@v4 action. - name: Deploy to GitHub Pages + #Assigns an ID to this step so that its outputs can be accessed by other steps (like setting the environment URL). + #I hope this detailed explanation helps you with your documentation. Let me know if you have any other questions or need + #further assistance with other parts of the workflow file. id: deployment uses: actions/deploy-pages@v4 # Release Info Generation Job # Creates version numbers and release notes + #This defines the job for generating release information, such as version numbers and changelogs. generate_release_info: name: Generate Release Info runs-on: ubuntu-latest + # Defines the outputs that this job will produce, which can be used by other jobs in the workflow. outputs: - version: ${{ steps.rel_number.outputs.version }} - version_code: ${{ steps.rel_number.outputs.version-code }} - steps: + version: ${{ steps.rel_number.outputs.version }} #Outputs the version number generated by the rel_number step. + version_code: ${{ steps.rel_number.outputs.version-code }} # Outputs the version code generated by the rel_number step. + steps: #Defines the sequence of steps to be executed within the job. - uses: actions/checkout@v4 + #Fetches the complete commit history, which is necessary for generating release notes based on Git commits. with: fetch-depth: 0 # Setup Java environment + #Sets up the Java development environment using the actions/setup-java@v4 action. This might be needed for some dependencies + #or build tools used in the release information generation process. - uses: actions/setup-java@v4 with: java-version: 17 distribution: 'temurin' # Configure Gradle + # Configures the Gradle build tool using the gradle/actions/setup-gradle@v4 action. + #This might be needed if the release information generation process involves Gradle tasks. - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 # Generate version number + #This step uses a custom action located at .github/actions/create-release-number within the + #repository to generate the release number and version code. - uses: ./.github/actions/create-release-number name: Create Release Number + #Assigns an ID to this step so that its outputs can be accessed by other steps. id: rel_number # Create release notes + # This step uses another custom action located at .github/actions/create-release-notes to generate release notes. - uses: ./.github/actions/create-release-notes name: Create Release Notes - with: + with: #Provides input values to the custom action. + #Passes the version number generated by the rel_number step as the tag name for the release notes. tag-name: ${{ steps.rel_number.outputs.version }} + # Passes the GITHUB_TOKEN secret, which is automatically provided by GitHub Actions, to authenticate with the GitHub API for accessing release information. gh-token: ${{ secrets.GITHUB_TOKEN }} # Save GitHub changelog + #Uploads the generated GitHub changelog as an artifact using the actions/upload-artifact@v4 action. - name: Upload GitHub Changelog uses: actions/upload-artifact@v4 with: name: git-changelog + #Defines the path to the changelog file to be uploaded. path: './mifospay-android/build/outputs/changelogGithub' # Save beta changelog + #Uploads the generated beta changelog as an artifact using the actions/upload-artifact@v4 action. - name: Upload Beta Changelog uses: actions/upload-artifact@v4 with: name: beta-changelog + #: Defines the path to the changelog file to be uploaded. I hope this detailed explanation helps you with your documentation. + #Let me know if you have any other questions or need further assistance with other parts of the workflow file path: './mifospay-android/build/outputs/changelogBeta' # GitHub Release Job # Creates GitHub release with all built artifacts github_release: name: Create Github Release + #Specifies that this job depends on the successful completion of the build and release information generation jobs for all platforms (Android, desktop, web, iOS). needs: [ build_android, build_desktop, build_web, build_ios, generate_release_info ] + #This job will only run if the release_type input is set to beta when the workflow is triggered. + #This indicates that this job is specifically for creating beta releases. if: inputs.release_type == 'beta' runs-on: ubuntu-latest + # Checks out the repository code using the actions/checkout@v4 action. steps: - uses: actions/checkout@v4 + #Fetches the complete commit history, which might be necessary for including commit information in the release. with: fetch-depth: 0 # Get all build artifacts + #Downloads all the build artifacts from previous jobs using the actions/download-artifact@v4 action. - name: Download All Artifacts uses: actions/download-artifact@v4 + #Defines the local directory where the downloaded artifacts will be stored. with: path: ./all-artifacts # Debug: Show downloaded files + # Executes the ls -R ./all-artifacts command to list the downloaded artifacts and their directory structure. + #This is a debugging step to verify the downloaded files. - name: Display structure of downloaded files run: ls -R ./all-artifacts - # Create ZIP archive of web app + #Creates a ZIP archive of the web app build using PowerShell. - name: Archive Web Build - shell: pwsh + shell: pwsh #Specifies that the step should use PowerShell as the shell. + # Executes the Compress-Archive command to create the ZIP archive. run: | Compress-Archive -Path './all-artifacts/web-app/*' -DestinationPath './all-artifacts/mifospay-web-app.zip' # Rename Ubuntu desktop artifact for consistency + #Renames the Ubuntu desktop app artifact (DEB file) to a more user-friendly name. - name: Rename Ubuntu Desktop Artifact + #Executes the mv command to rename the file. run: | mv ./all-artifacts/desktop-app-ubuntu-latest/mifoswallet_1.0.0-1_amd64.deb ./all-artifacts/desktop-app-ubuntu-latest/MifosWallet-1.0.0.deb # Get changelog for release + #Downloads the Git changelog artifact generated in the generate_release_info job. - name: Download Git Changelog uses: actions/download-artifact@v4 with: @@ -643,10 +886,16 @@ jobs: - name: Create Github Pre-Release uses: softprops/action-gh-release@v2.0.8 with: + #Sets the tag name for the release to the version generated in the generate_release_info job. tag_name: ${{ needs.generate_release_info.outputs.version }} + #Sets the release description to the contents of the downloaded Git changelog file. body_path: ./all-artifacts/git-changelog/changelogGithub + #Indicates that the release should not be a draft (i.e., it should be published immediately). draft: false prerelease: true + #Specifies the files to be included in the release, which are the built artifacts for all platforms. + #I hope this detailed explanation helps you with your documentation. Let me know if you have any other questions + #or need further assistance with other parts of the workflow file. files: | ./all-artifacts/android-app/prod/release/mifospay-android-prod-release.apk ./all-artifacts/android-app/demo/release/mifospay-android-demo-release.apk diff --git a/.github/workflows/make_site.yaml b/.github/workflows/make_site.yaml index f18d750ce..ae546d05d 100644 --- a/.github/workflows/make_site.yaml +++ b/.github/workflows/make_site.yaml @@ -1,39 +1,46 @@ +#This workflow is designed to automate the process of building and deploying a Kotlin/JS web application to GitHub Pages. +#It ensures that whenever changes are merged into the dev branch or when manually triggered, the web application is built, +#packaged, and deployed to the GitHub Pages environment, making it accessible online. + # Workflow to build and deploy the web application to GitHub Pages name: Publish Web App # Trigger conditions for the workflow on: # Trigger on pull request close events to the dev branch + # Automatically triggers the workflow when a pull request is closed and merged into the dev branch. pull_request: branches: [ "dev" ] types: [ closed ] - # Manual trigger option from GitHub Actions UI + # Allows Manual trigger option from GitHub Actions UI workflow_dispatch: # Concurrency settings to manage multiple workflow runs # This ensures orderly deployment to production environment concurrency: + #Groups workflow runs related to GitHub Pages deployment. group: "pages" - # Don't cancel running deployments to ensure production stability + # Prevents cancellation of in-progress deployments to ensure stability, especially in production environments. cancel-in-progress: false jobs: # Main job to build and deploy the web application build_web_app: # Configure deployment environment and URL + #Specifies the deployment environment as github-pages and sets the URL using the output from the deployment step. environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} # Use Windows runner for build environment runs-on: windows-latest - # Required permissions for GitHub Pages deployment + # Grants necessary permissions for reading repository contents, writing to GitHub Pages, and writing authentication tokens. permissions: contents: read # Read repository contents pages: write # Write to GitHub Pages id-token: write # Write authentication tokens steps: - # Step 1: Check out the repository code + # Step 1: Check out the repository code to the runner - uses: actions/checkout@v4 # Step 2: Set up Java development environment @@ -42,7 +49,7 @@ jobs: distribution: 'zulu' # Use Zulu distribution of OpenJDK java-version: 17 # Use Java 17 version - # Step 3: Build the Kotlin/JS web application + # Step 3:Executes the Gradle task jsBrowserDistribution to Build the Kotlin/JS web application - name: Build Web(JS) App run: ./gradlew jsBrowserDistribution @@ -50,14 +57,14 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v5 - # Step 5: Upload the built web application as an artifact + # Step 5: Upload the built web application as an artifact to GitHub pages - name: Upload static files as artifact uses: actions/upload-pages-artifact@v3 with: # Path to the built web application files path: './mifospay-web/build/dist/js/productionExecutable/' - # Step 6: Deploy the artifact to GitHub Pages + # Step 6: Deploy the artifact to GitHub Pages, making the web application live. - name: Deploy to GitHub Pages id: deployment # ID used for environment URL output uses: actions/deploy-pages@v4