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. Publishing is automated through GitHub Actions.

1. **Bump version ** in opengraphkt/build.gradle.kts:

   version = "0.1.4"
   

2. Publish to local Maven for testing (optional):

   ./gradlew publishToMavenLocal
   

3. Create GitHub release (this triggers the publishing workflow):

   • Go to GitHub repository → Releases → "Draft a new release"
   • Click "Choose a tag" and create a new tag (e.g., v0.1.3)
   • Set the release title (e.g., v0.1.3)
   • Add release notes describing changes
   • Click "Publish release"

4. GitHub Actions will automatically:

   • Build the project
   • Run tests
   • Publish to Maven Central
   • The workflow is triggered automatically when you create a new release

5. After a few minutes, you will see the new version in Maven Central. You can also directly check the real-time status on Central Sonartype.

Post-Release Steps

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

   version = "0.1.5-SNAPSHOT"
   

2. Commit version bump:

   git commit -am "Bump version to 0.1.5-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!