**Table of Contents** 1. Introduction 2. Pre-requisites - Usage Scenario Scripts 3. Usage - Ceate Fork - Place the files in `test_scripts` folder - Push Changes - Create a merge request 4. Pipeline execution and Access the result - Downloading Artifacts and Reports # Introduction Welcome to KEcoLab’s User Guide! **KEcoLab** project aims to provide a streamlined process for measuring software energy consumption remotely using a CI/CD pipeline. By automating the measurement process, users can make informed decisions to improve code efficiency and sustainability of the software. This project helps developers to make informed decisions to improve code efficiency and obtain software eco-certification with the [Blue Angel](https://eco.kde.org/handbook)(Certification is optional). This guide will provide you with step-by-step instructions on how you can measure your software’s energy consumption through KEcoLab. # Pre-requisites Before measuring your software’s energy consumption, make sure to prepare the following: * Software/Application should be packaged as a flatpak and uploaded on flathub * Usage scenario script for the software ## Usage Scenario Scripts Usage scenario scripts are a set of shell commands that defines the most common or resource-heavy actions of the software across different operational modes: idle, baseline, and sus. During the **idle mode** your software will be opened but no action is performed, in **baseline mode** only the operating system will be running, and in **SUS mode** your software will be opened and most commonly used/ resource-heavy actions will be executed. You need to prepare three files written in shell commands: idle.sh, baseline.sh, and sus.sh. Additionally, if you want to write any configurations for the software, you can add that in configuration.sh and attach with other files. # Usage Follow these steps to measure your software's energy consumption. ## Create a Fork As a first step, you need to fork the KEcoLab repository. Navigate to [this](https://invent.kde.org/sdk/kecolab/) link and click the `Fork` button in the right corner.  Do not change the project name and project slug. Under the `select a namespace`, select your `username` and click `create fork`.  You can either use WebIDE or your local machine. ### Using Local Machine If you choose to use your local machine, click code > copy the link under clone with HTTPS.  Open a terminal on your local machine and copy and paste the command below to clone the repository on your local machine. Replace the `<copied_link>` with the actual link you copied before. `git clone <copied_link>`  The next step is to create a new branch for your software. Copy the command below to create a new branch and replace `<branch_name>` with the name of your choice. `git checkout <branch_name>`  ### Using WebIDE Click `edit fork in WebIDE` which is present next to the code.  Once the IDE is opened, click `master` in the bottom left corner of the IDE and choose `create new branch`.  ## Place the files in `test_scripts` folder The next step is to organize the scripts you created and add them to a folder. Navigate to this location: `scripts` > `test_scripts`. Inside the `test_scripts` folder, create a new folder for your software.  The name of the folder should be the same as the name of the software under which the application is published on Flathub. Upload all the scripts (i.e., baseline.sh, idle.sh, sus.sh and configuration.sh) into the newly created folder. ## Push Changes After uploading the files, create a commit with a message. Follow the instructions below to create a commit. - Using Local Machine Before committing your changes, you need to stage the changes using the git command `git add .` This will add all the unstaged files. To create a commit on your local machine, paste the below command in your terminal. Replace `<software_name>` with your software name. `git commit -m “Uploaded files for <software_name> energy measurement.”`  Once you commit the changes on your local machine, it’s time to push the changes to the forked repository. Paste the command in your terminal, and do not forget to replace `<branch_name>` with your new branch name. `git push origin <branch_name>`  - Using WebIDE To stage the changes in WebIDE, go to `source control` that is present in the left navbar.  Enter a commit message similar to this _**‘Uploaded files for kate software energy measurement’** _ and click `commit and push to new_branch` button. This will push the changes to your new branch you created.  Once you successfully commit the changes, you will see the 'Success' message. And the next step is to create a merge request. ## Create a merge request After pushing the changes to the new branch, go to the forked repository page. You will see a notification to create a merge request. Click `create merge request` button.  Add the title of the merge request, which must reflect the name under which the application is published on flathub. i.e., if the application name is _‘org.kde.kate’_ then the title of the merge request is also _‘org.kde.kate’_. Failing to do so, you will encounter errors in the measurement process.  [Note: This step is same for both local machine and WebIDE process.] # Pipeline execution and Accessing Results The next step is pipeline execution. Successfully creating a merge request will trigger the pipeline defined for measuring the energy consumption of software. During the execution of the pipeline, three jobs will run.  The first job is **build**. In the build job process, the pipeline will define and prepare all the necessary files and environments required for the measurement process.  The second job is **measurement**. In this job, the actual measurement of the energy consumption will take place. The measurement process will execute for each mode of the software, i.e., idle, baseline, and sus. The measurement will approximately execute for 30 iterations to get the most accurate results for each mode.  The last job is **result**. Upon successfully executing all the jobs, you can download the results it generated.  ## Downloading Artifacts and Reports On successful completion of the pipeline, you will be able to download the artifacts and reports from the merge request page you created. In the artifacts folder, you can see two reports. **Idle_Report** report is for idle mode, and **Sus_Report** is for sus mode. You can find the measurement details inside the reports. Other folders includes the artifacts used to create the reports.