2 ‐ Contribution Guidelines - DefinetlyNotAI/Logicytics GitHub Wiki

How to Contribute

Contributing to open-source projects is a rewarding way to give back to the community while enhancing your skills. Here's how you can get started:

  1. Fork the Repository: Visit the project's GitHub page and click on the 'Fork' button at the top right corner. This creates a copy of the repository in your GitHub account.

  2. Clone the Repository: Clone the forked repository to your local machine using Git. Open your terminal or command prompt and run:

    git clone https://github.com/DefinetlyNotAI/Logicytics.git

  3. Create a New Branch: It's good practice to create a new branch for your changes. This keeps the main branch clean and makes merging easier. Run:

    git checkout -b feature/your-feature-description

    Replace your-feature-description with your feature description.

  4. Make Your Changes: Navigate through the files and make your contributions. Remember to adhere to the project's coding standards and practices outlined below.

  5. Commit Your Changes: After making your changes, stage them for commit. Then, commit with a meaningful message:

    git add.
git commit -m "Your descriptive commit message"

  6. Push Your Changes: Push your committed changes to your forked repository on GitHub:

    git push origin feature/your-feature-description

  7. Open a Pull Request (PR): Go to your forked repository on GitHub, switch to your feature branch, and click 'New pull request'. Fill out the form, describing your changes and why they should be included. Submit the PR for review.

Contributors

Contributors play a vital role in the growth and success of open-source projects. They come in various forms, each contributing uniquely:

Functionality Adders

These contributors introduce new features and functionalities to the project. Their work expands the capabilities of the software, often requiring deep understanding and innovative thinking.

Code Cleaners

Code cleaners focus on improving the existing codebase. They ensure the code is efficient, readable, and adheres to best practices. This might involve refactoring, optimizing performance, or simplifying complex logic.

QoL Enhancers

Quality of Life (QoL) enhancers improve the usability and enjoyment of the software without necessarily adding new features. This could include UI improvements, documentation updates, or bug fixes that significantly impact user experience.

Bug Hunters

Basic Code Practices

When contributing code, it's crucial to maintain consistency and readability. Here are some key practices:

  • Coding Style: Align your code with the project's established coding style. This might involve consistent indentation, naming conventions, and more.
  • Docstrings and Comments: Include comprehensive docstrings for functions and classes, explaining their purpose, parameters, and return values. Use comments sparingly to explain why certain decisions were made.
  • Functions and Modularity: Break down your code into reusable functions and modules. This enhances readability and maintainability.

File Adding

When adding new files to the project, consider the following guidelines:

  • Language Preference: Prefer Python, Batch, or PowerShell for compatibility and ease of maintenance. However, if another language is necessary, ensure it's well-documented and easily maintainable.
  • File Naming and Organization: Follow the project's directory structure and naming conventions. Organize files logically to facilitate easy navigation and understanding.

Coding Rules

Printing Rules

Consistent logging and output formatting are essential for debugging and monitoring. Here are the rules:

  • Python Users: Utilize colorlog for coloured output and structured logging. Avoid using print() directly; reserve it for newline characters.
  • Other Languages: Start messages with appropriate keywords (INFO, WARNING, ERROR) followed by the message. For example, "INFO Your Message".

Crash Reporting Mechanism

Below are the crash reporting mechanisms for Python and PowerShell. Select the appropriate section based on the language you are using, you may need to develop your own function for other languages for this specific user-case.

Python Crash Reporting Mechanism

import os
import subprocess


def crash(error_id, function_no, error_content, type):
    # Ensure error_id and function_no are strings
    error_id = str(error_id)
    function_no = str(function_no)

    # Prepare the data to write to the temporary files
    script_name = os.path.basename(__file__)
    language = os.path.splitext(__file__)[1][1:]  # Extracting the language part

    # Write the name of the placeholder script to the temporary file
    with open("flag.temp", 'w') as f:
        f.write(script_name)

    # Write the error message to the temporary file
    with open("error.temp", 'w') as f:
        f.write(error_id)

    # Write the name of the placeholder function to the temporary file
    with open("function.temp", 'w') as f:
        f.write(function_no)

    # Write the name of the placeholder language to the temporary file
    with open("language.temp", 'w') as f:
        f.write(language)

    # Write the name of the placeholder crash to the temporary file
    with open("error_data.temp", 'w') as f:
        f.write(error_content)

    with open("type.temp", 'w') as f:
        f.write(type)

    # Open Crash_Reporter.py in a new shell window
    # Note: This command works for Command Prompt. Adjust according to your needs.
    process = subprocess.Popen(r'powershell.exe -Command "& .\Crash_Reporter.py"', shell=True,  stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
    for line in iter(process.stdout.readline, b''):
        decoded_line = line.decode('utf-8').strip()
        print(decoded_line)
    # Wait for the process to finish and get the final output/error
    stdout, _ = process.communicate()
    # Decode the output from bytes to string
    stdout = stdout.decode('utf-8') if stdout else ""
    print(stdout)

Where now you may incorporate into any caught error the following line

crash("error_id", "function_no", "crash_msg", "crash_type")

replacing error_id with an ID found in the Error ID page in this wiki and replacing function_no with the code line the function was written in (including the key word fun# in it), and replace crash_msg with your error message (usually the raw error data that was caught) and finally replace crash_type with either crash or error depending if you want to register it as a crash or not, do note crashes will open a error screen.

PowerShell Crash Reporting Mechanism

function Invoke-CrashReport {
    param(
        [string]$ErrorId,
        [string]$FunctionNo,
        [string]$ErrorContent,
        [string]$Type
    )

    # Prepare the data to write to the temporary files
    $ScriptName = Split-Path -Leaf $PSCommandPath
    $Language = "ps1" # Since this is a PowerShell script, the language is PowerShell

    # Write the name of the placeholder script to the temporary file
    Set-Content -Path "flag.temp" -Value $ScriptName

    # Write the error message to the temporary file
    Set-Content -Path "error.temp" -Value $ErrorId

    # Write the name of the placeholder function to the temporary file
    Set-Content -Path "function.temp" -Value $FunctionNo

    # Write the name of the placeholder language to the temporary file
    Set-Content -Path "language.temp" -Value $Language

    # Write the name of the placeholder crash to the temporary file
    Set-Content -Path "error_data.temp" -Value $ErrorContent

    # Write the type to the temporary file
    Set-Content -Path "type.temp" -Value $Type

    # Execute Crash_Reporter.py in a new shell window and capture its output
    # Note: Adjust the path to Crash_Reporter.py as necessary
    $ProcessInfo = New-Object System.Diagnostics.ProcessStartInfo
    $ProcessInfo.FileName = "powershell.exe"
    $ProcessInfo.RedirectStandardOutput = $true
    $ProcessInfo.UseShellExecute = $false
    $ProcessInfo.Arguments = "-Command python .\Crash_Reporter.py" # Adjusted to run Python script

    $Process = New-Object System.Diagnostics.Process
    $Process.StartInfo = $ProcessInfo
    [void]$Process.Start()

    # Read the output
    while (-not $Process.StandardOutput.EndOfStream) {
        $line = $Process.StandardOutput.ReadLine()
        Write-Host $line
    }

    # Wait for the process to exit
    $Process.WaitForExit()
}

Where now you may incorporate into any caught error the following line

Invoke-CrashReport -ErrorId "error_id" -FunctionNo "function_no" -ErrorContent "crash_msg" -Type "crash_type")

replacing error_id with an ID found in the Error ID page in this wiki and replacing function_no with the code line the function was written in (including the key word fun# in it), and replace crash_msg with your error message (usually the raw error data that was caught) and finally replace crash_type with either crash or error depending if you want to register it as a crash or not, do note crashes will open a error screen.

Credits

Acknowledge your contributions appropriately in the CREDITS.md file. Use the following template:

### File-Created by Your-Username
What you did, created, removed, or refactored.
- [Your GitHub Username](Your GitHub Link)

This ensures proper attribution and recognition for your efforts.

By following these guidelines and practices, you can effectively contribute to open-source projects, enhancing both your skills and the broader community's knowledge and tools.