Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (164 loc) · 7.84 KB

CONTRIBUTING.md

File metadata and controls

202 lines (164 loc) · 7.84 KB

Contributing to ISBN Validator and Generator

Thank you for your interest in contributing to ISBN Validator and Generator! We welcome contributions from the community, including bug reports, feature requests, code improvements, and documentation enhancements. This guide outlines how to get involved and help improve this open-source C utility.

Table of Contents

Code of Conduct

All contributors are expected to adhere to the Code of Conduct. This ensures a respectful and inclusive environment for everyone involved in the project.

How to Contribute

Reporting Bugs

If you encounter a bug in ISBN Validator and Generator:

  1. Check Existing Issues: Search the Issues page to see if the bug has already been reported.
  2. Create a New Issue: If the bug is new, open a new issue and provide:
    • A clear title and description of the bug.
    • Steps to reproduce the issue (e.g., specific ISBN input, menu choice).
    • Expected and actual behavior.
    • Your environment (e.g., OS, compiler, version).
    • Any error messages or logs.
  3. Use the Bug Report Template: Follow the template provided in the issue creation form for consistency.

Example Bug Report:

  • Title: "Invalid ISBN-10 with Whitespace Accepted"
  • Description: Entering an ISBN-10 with leading/trailing spaces causes incorrect validation.
  • Steps: Select option 1, enter " 0306406152 ", observe result.
  • Expected: Input rejected as invalid.
  • Actual: Validates as correct.
  • Environment: GCC 11.2, Ubuntu 22.04.

Suggesting Features

We welcome ideas to enhance ISBN Validator and Generator! To suggest a feature:

  1. Check Existing Requests: Review the Issues page to avoid duplicates.
  2. Submit a Feature Request: Open a new issue and include:
    • A clear title and detailed description of the feature.
    • The problem it solves or the benefit it provides (e.g., adds batch validation, improves portability).
    • Any relevant examples or references to similar tools.
  3. Use the Feature Request Template: Follow the provided template to structure your suggestion.

Example Feature Request:

  • Title: "Add Batch ISBN Validation from File"
  • Description: Allow users to validate multiple ISBNs from a text file.
  • Benefit: Useful for publishers processing large datasets.

Submitting Pull Requests

To contribute code or documentation:

  1. Fork the Repository:

  2. Create a Branch:

    • Create a new branch for your changes: 
      git checkout -b feature/your-feature-name
    • Use descriptive branch names (e.g., fix/input-validation, feature/batch-validation).

  3. Make Changes:

    • Implement your changes in the codebase or documentation.
    • Follow the Code Style Guidelines below.
    • Test your changes across multiple platforms (e.g., Linux, Windows).

  4. Commit Changes:

    • Write clear, concise commit messages: 
      git commit -m "Add feature: batch ISBN validation from file"
    • Reference related issues (e.g., Fixes #123).

  5. Push and Create a Pull Request:

    • Push your branch to your fork: 
      git push origin feature/your-feature-name
    • Open a pull request (PR) against the main branch of the original repository.
    • Use the PR template and provide:
      • A description of the changes.
      • The issue number(s) addressed (if any).
      • Testing performed (e.g., platforms tested, edge cases).

  6. Code Review:

    • Respond to feedback from maintainers.
    • Make requested changes and update your PR as needed.
    • Your PR will be merged once approved.

Development Setup

To set up a development environment for ISBN Validator and Generator:

  1. Prerequisites:

    • A C compiler (e.g., GCC, Clang, MSVC).
    • Git for version control.
    • A code editor (e.g., VS Code, Vim).
    • (Optional) make for build automation.

  2. Clone the Repository:

    git clone https://github.com/VoxDroid/ISBN-Validator-Generator.git
cd ISBN-Validator-Generator

  3. Compile the Code:

    • Using GCC/Clang: 
      gcc main.c -o isbn_validator
    • Using MSVC: 
      cl main.c /o isbn_validator.exe
    • Or use a Makefile (see Installation in README).

  4. Test the Application:

    • Run the executable: 
      ./isbn_validator
    • Verify menu options work (validate ISBN, generate fake/real ISBNs).
    • Test with sample ISBNs (e.g., 0306406152, 9780306406157).

Code Style Guidelines

To maintain consistency in the codebase:

  • C Code:
    • Use 4-space indentation.
    • Follow K&R style for braces: 
      if (condition) {
    // code
} else {
    // code
}
    • Use meaningful variable and function names (e.g., calculate_isbn10_checksum).
    • Add comments for complex logic or functions.
    • Keep functions concise and focused (e.g., separate validation and checksum logic).
  • Error Handling:
    • Validate all user inputs (e.g., check for non-numeric characters).
    • Provide clear error messages for invalid inputs.
  • Portability:
    • Use standard C libraries only (stdio.h, stdlib.h, etc.).
    • Avoid platform-specific code unless necessary (e.g., Windows-specific file handling).
  • Documentation:
    • Update README.md for new features or changes to usage.
    • Add inline comments for non-obvious code sections.
  • File Structure:
    • Keep all source code in main.c unless modularization is needed.
    • Place additional files (e.g., tests) in a tests/ directory if added.

Testing

Before submitting a pull request:

  • Manual Testing:
    • Test all menu options (validate, generate fake/real ISBNs, exit).
    • Validate known ISBNs (e.g., 0-306-40615-2, 978-0-306-40615-7).
    • Generate fake ISBNs and confirm they fail validation.
    • Generate real ISBNs and confirm they pass validation.
  • Edge Cases:
    • Test invalid inputs (e.g., letters, whitespace, incorrect lengths).
    • Test ISBN-10 with 'X' as checksum.
    • Test empty or malformed input (e.g., hyphens only).
  • Platform Testing:
    • Compile and run on multiple platforms (e.g., Linux, Windows, macOS).
    • Verify with different compilers (e.g., GCC, Clang, MSVC).
  • Performance:
    • Ensure checksum calculations are efficient for large inputs.
    • Test with rapid input sequences to check input buffer handling.
  • Unit Tests (if added):
    • Write tests for validate_isbn10, validate_isbn13, calculate_isbn10_checksum, and calculate_isbn13_checksum.
    • Use a framework like Check or CUnit if implementing tests.

Community

Join the ISBN Validator and Generator community:

  • GitHub Discussions: Share ideas or ask questions in the Discussions section.
  • Issues: Report bugs or suggest features on the Issues page.
  • GitHub Stars: Show your support by starring the repository.

Thank you for contributing to ISBN Validator and Generator! Your efforts help make this tool better for users worldwide.