OpenGraphKt/CONTRIBUTING.md

Contributing to OpenGraphKt

Thank you for your interest in contributing to OpenGraphKt! This document provides guidelines and instructions for contributing to the project.

Development Setup

Prerequisites

• Java 24 (JVM toolchain)
• Gradle 8.14.3+ (wrapper included)
• Git

Getting Started

1. Clone the repository:

   git clone https://github.com/jlengrand/OpenGraphKt.git
   cd OpenGraphKt
   

2. Build the project:

   ./gradlew build
   

3. Run tests:

   ./gradlew test
   

4. Check code coverage:

   ./gradlew koverXmlReport
   ./gradlew koverVerify  # Enforces 70% minimum coverage
   

Project Structure

• opengraphkt/ - Core library module (published to Maven Central)
• demo/ - Local file parsing examples
• demo-remote/ - Remote URL parsing examples using published artifact
• scrape-test/ - Testing/scraping utilities

Making Changes

Code Style

• Follow Kotlin coding conventions
• Use meaningful variable and function names
• Add KDoc comments for public APIs

Testing

• Write tests for all new functionality
• Maintain minimum 70% code coverage (enforced by Kover)
• Run tests locally before submitting PR: ./gradlew test

Commits

• Write clear, concise commit messages
• Reference issue numbers when applicable
• Keep commits focused and atomic

Submitting Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Run tests and ensure coverage: ./gradlew test koverVerify
5. Commit your changes
6. Push to your fork
7. Submit a Pull Request

Publishing New Versions

This section is for maintainers only.

Version Numbering

OpenGraphKt follows Semantic Versioning:

• MAJOR version for incompatible API changes
• MINOR version for backwards-compatible functionality additions
• PATCH version for backwards-compatible bug fixes

Pre-Release Checklist

1. Update version number in opengraphkt/build.gradle.kts:

   version = "0.1.3-SNAPSHOT"  // Change to "0.1.3" for release
   

2. Update demo-remote dependency in demo-remote/build.gradle.kts:

   dependencies {
       implementation("fr.lengrand:opengraphkt:0.1.3")  // Match release version
   }
   

3. Run full test suite:

   ./gradlew clean build test koverVerify
   

4. Test demo applications:

   ./gradlew :demo:run
   ./gradlew :demo-remote:run
   

Publishing to Maven Central

The project uses the com.vanniktech.maven.publish plugin for publishing.

1. Configure credentials (first time only):

   • Set up Sonatype Central Portal account
   • Configure GPG signing keys
   • Add credentials to ~/.gradle/gradle.properties:

     mavenCentralUsername=your-username
     mavenCentralPassword=your-password
     signing.keyId=your-key-id
     signing.password=your-key-password
     signing.secretKeyRingFile=/path/to/secring.gpg
     

2. Publish to local Maven for testing:

   ./gradlew publishToMavenLocal
   

3. Publish to Maven Central:

   ./gradlew publishAllPublicationsToMavenCentral
   

4. Create Git tag and push:

   git tag v0.1.3
   git push origin v0.1.3
   

5. Create GitHub release:

   • Go to GitHub repository → Releases
   • Create new release from the tag
   • Add release notes describing changes

Post-Release Steps

1. Bump version to next SNAPSHOT in opengraphkt/build.gradle.kts:

   version = "0.1.4-SNAPSHOT"
   

2. Commit version bump:

   git commit -am "Bump version to 0.1.4-SNAPSHOT"
   git push
   

Questions?

If you have questions or need help, please:

• Open an issue on GitHub
• Check existing issues and discussions

Thank you for contributing to OpenGraphKt!