Table of Contents

01. Getting Started

01.01. Basic Usage

This guide will walk you through the process of setting up and customizing the INI Configurator to create your own configuration editor application. The configurator allows you to design a custom graphical interface for managing .ini files by modifying fields and constants.

Step 1: Fork the Repository

  1. Navigate to the GitHub repository LaswitchTech/ini-configurator.
  2. Click the Fork button in the top-right corner to create your own copy of the repository under your GitHub account.

Step 2: Set Up a Development Branch

  1. Go to your forked repository.
  2. Create a new branch named dev:
    • In GitHub, go to the Code tab.
    • Click the branch dropdown, type dev, and select Create branch: dev.
  3. This branch will be used to compile your .exe file and manage development.

Step 3: Clone the Repository Locally

  1. Clone your forked repository using Git: 
    git clone -b dev https://github.com/<your-username>/ini-configurator.git
cd ini-configurator
  2. Verify that you are on the dev branch: 
    git branch

Step 4: Customize the Application

Modify the fields.json File

The src/lib/fields.json file defines the sections and fields displayed in the configurator. Update this file to specify the .ini configuration options you want to manage.

Example: Here’s an example of a fields.json entry:

fields.json
{
    "General": {
        "appName": {
            "label": "Application Name",
            "tooltip": "The name of your application",
            "type": "text",
            "default": "MyApp",
            "required": true
        },
        "debugMode": {
            "label": "Enable Debugging",
            "tooltip": "Enable or disable debug mode",
            "type": "checkbox",
            "default": "false",
            "required": false
        }
    }
}

Update Constants in configurator.py

At the start of the src/configurator.py script, modify the constants to set your application name, .ini file name, and debugging preferences: 

# Declare Constants
APP_NAME = "INI Configurator"
INI_FILE = "conf.ini"
LOG_FILE = "log.log"
ENCODING = "mbcs" if sys.platform == "win32" else "utf-8"
DEBUG = False
  • APP_NAME: Name of your application.
  • INI_FILE: Name of the .ini file that will be managed.
  • LOG_FILE: Name of the log file.
  • ENCODING: This constant sets the default encoding method for the .ini file.
  • DEBUG: Set to True for debugging during development.

Step 5: Use Utility Scripts

iconset.sh

This script converts your src/icons/icon.png file into icon formats suitable for Windows and macOS.

Usage:

  1. Place your custom icon in src/icons/icon.png.
  2. Run the script: 
    ./iconset.sh
  3. The script generates the required icon files for your application.

build.sh

This script compiles the configurator for macOS. Usage: Run the script: 

./build.sh

The compiled macOS .app file will be created in the dist/macos directory.

Step 6: Compile for Windows

To compile the .exe file for Windows:

  1. Push your changes to the dev branch: 
    git add .
git commit -m "Customize fields.json and constants"
git push origin dev
  2. GitHub Actions will automatically build the .exe file. It uses the build.yml workflow in the .github/workflows/ directory.

Step 7: Test and Refine

  1. Run the application locally or test the .exe or .app files to ensure everything works as expected.
  2. Refine the fields, constants, or icons as needed.
  3. Repeat the build process after each update.

Optional: Enable Debugging

If you encounter issues during development, set DEBUG = True in src/configurator.py. This enables logging of additional details to help troubleshoot problems.

Notes

  • File Paths: Ensure all resource paths in your code (e.g., icons, stylesheets) work for both development and compiled environments. Use the self.resource_directory constant in src/configurator.py to access files dynamically.
  • Branch Management: Keep the main branch clean for releases. Use dev for development and testing.

Conclusion

By following this guide, you can easily set up, customize, and build your own version of the INI Configurator. Enjoy creating your custom configuration editor!

01.02. Creating a Release

Once you’ve finished customizing and testing your configurator, follow these steps to create a release version:

Step 1: Create a Pull Request to Merge dev into stable

  1. Go to your forked repository on GitHub.
  2. Navigate to the Pull Requests tab and click New pull request.
  3. Set the base branch to stable and the compare branch to dev.
  4. Review the changes in the pull request and click Create pull request.
  5. Once the pull request is created, review and merge it into the stable branch.

Step 2: Tag the Stable Branch for a Release

  1. After merging, ensure you are on the stable branch: 
    git checkout stable
git pull origin stable
  2. Create a version tag for the release: 
    git tag v1.0.0
git push origin v1.0.0
    1. Replace v1.0.0 with your desired version number following semantic versioning conventions (e.g., v1.1.0, v2.0.0).

Step 3: Trigger the Release Workflow

The push of a version tag (e.g., v1.0.0) to the stable branch will automatically trigger the GitHub Actions workflow for creating a release. This workflow will:

  • Package the application for both Windows (.exe) and macOS (.app).
  • Upload the compiled files as assets to the release in GitHub.

Step 4: Download the Release

  1. Once the release workflow is complete, go to the Releases section in your repository.
  2. Find the newly created release (e.g., v1.0.0).
  3. Download the compiled assets (Configurator.exe for Windows and Configurator.app for macOS).

Notes for Releases

  • Branch Management: Keep the stable branch clean and only merge fully tested changes from the dev branch.
  • Versioning: Use semantic versioning for tags (vX.Y.Z) to indicate major, minor, and patch updates.
  • Automated Workflow: Ensure your GitHub Actions workflows (build.yml and others) are correctly configured for release tagging.

Conclusion

By following these steps, you’ll ensure a smooth release process and maintain a clear separation between development and production code.