Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
230 lines (167 loc) · 6.16 KB

CONTRIBUTING.md

File metadata and controls

230 lines (167 loc) · 6.16 KB

Contributing to Log File Generator

Thank you for your interest in contributing to the Log File Generator project! This document provides information about the solution structure, development setup, testing, and how to submit contributions.

Development Setup

Prerequisites

  • .NET 8.0 SDK or later
  • Git
  • A code editor (Visual Studio, VS Code, or Rider recommended)

Clone the Repository

git clone https://github.com/Insight-NA/log-file-generator.git
cd log-file-generator

Project Structure

LoggerApplication/
├── src/
│   ├── Program.cs                 # Main application logic
│   └── LoggerApplication.csproj   # Project file
├── tests/
│   └── LoggerApplication.Tests/
│       ├── LoggerApplicationTests.cs    # Integration tests
│       └── LoggerApplication.Tests.csproj
├── .github/
│   └── workflows/
│       └── build-release.yml      # CI/CD pipeline
├── LoggerApplication.sln           # Solution file
├── params.txt                      # Example parameter file
├── README.md                       # User documentation
└── CONTRIBUTING.md                 # This file

Solution Architecture

Program.cs

The main application consists of several key components:

  • Main Method: Reads and parses the parameter file, validates configurations, and starts multiple logger threads
  • LoggerConfig Class: Holds configuration for each simulated application (log rate, file size, directory)
  • RunLogger Method: Executes on separate threads with CancellationToken support for graceful shutdown
  • RollingFileLogger Class: Manages file creation, rollover based on size, and writing log messages

Key Features

  • Multi-threading: Each configuration runs in its own thread using Task.Run()
  • Thread Safety: Each logger instance writes to its own directory, eliminating the need for locking
  • Graceful Shutdown: Console.CancelKeyPress event handler ensures clean termination
  • Random Timing: Log generation timing is randomized ±50% around the configured average

Building the Project

Debug Build

dotnet build

Release Build

dotnet build -c Release

Published Self-Contained Executable

dotnet publish -c Release -r win-x64 --self-contained

Output will be in src/bin/Release/net8.0/win-x64/publish/

Running Tests

Run All Tests

dotnet test

Run Specific Test Project

dotnet test tests/LoggerApplication.Tests/LoggerApplication.Tests.csproj

Test Coverage

The test suite includes 6 integration tests:

  1. Application_CreatesLogDirectory - Verifies directory creation
  2. Application_CreatesLogFilesWithCorrectNaming - Validates filename format (yyyyMMdd-HHmm.log)
  3. Application_WritesLogMessagesWithCorrectFormat - Checks log entry format
  4. Application_CreatesMultipleLogFilesWhenSizeExceeded - Tests file rollover behavior
  5. Application_FailsWithInvalidArguments - Validates error handling for invalid input
  6. Application_GeneratesUniqueGuidsPerMessage - Ensures unique GUIDs per log entry

All tests use temporary parameter files and clean up after execution.

CI/CD Pipeline

GitHub Actions Workflow

The project uses GitHub Actions for continuous integration and releases. The workflow (.github/workflows/build-release.yml) includes:

Triggers

  • Push to main: Runs build and tests
  • Pull requests: Validates changes before merging
  • Release creation: Builds and publishes artifacts

Jobs

  1. Build Job

    • Restores dependencies
    • Builds the solution
    • Runs all unit tests
    • Creates self-contained Windows x64 executable
    • Uploads build artifacts

  2. Release Job (on release creation only)

    • Downloads build artifacts
    • Creates ZIP package
    • Uploads to GitHub Release

Creating a Release

  1. Create and push a tag:

    git tag v1.0.0
git push origin v1.0.0

  2. Create a GitHub Release from the tag

  3. The workflow automatically builds and attaches LoggerApplication.zip

Making Changes

Workflow

  1. Fork the repository on GitHub
  2. Create a feature branch: 
    git checkout -b feature/your-feature-name
  3. Make your changes
  4. Run tests to ensure nothing breaks: 
    dotnet test
  5. Commit your changes with clear commit messages: 
    git commit -am "Add feature: description of what you added"
  6. Push to your fork: 
    git push origin feature/your-feature-name
  7. Open a Pull Request on GitHub

Code Style Guidelines

  • Follow standard C# naming conventions
  • Keep methods focused and single-purpose
  • Add XML documentation comments for public methods
  • Ensure all tests pass before submitting PR
  • Write tests for new features

Pull Request Checklist

  • Code builds successfully
  • All tests pass
  • New features include tests
  • README.md updated if user-facing changes
  • CONTRIBUTING.md updated if developer-facing changes
  • Clear description of changes in PR

Suggesting Changes

We welcome suggestions and improvements! Here's how to propose changes:

For Bug Reports

  1. Check if the issue already exists
  2. Create a new issue with:
    • Clear description of the bug
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, .NET version)

For Feature Requests

  1. Open an issue describing:
    • The problem you're trying to solve
    • Your proposed solution
    • Any alternative approaches considered

For Code Contributions

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes with tests
  4. Submit a pull request with:
    • Clear description of the changes
    • Link to related issue (if applicable)
    • Screenshots/examples if relevant

Questions?

If you have questions about contributing:

  • Open an issue on GitHub
  • Check existing issues and pull requests
  • Review this document and README.md

Code of Conduct

  • Be respectful and constructive
  • Focus on the code, not the person
  • Help others learn and improve
  • Assume good intentions

Thank you for contributing to Log File Generator!
⚡