Add Maven publishing support for GitHub Packages

[Copilot]

This PR implements Maven publishing for the lib module to GitHub Packages, enabling the library to be consumed as a dependency via Gradle dependency management.

Changes Made

• Added maven-publish plugin to lib/build.gradle.kts
• Configured project metadata:
  • groupId: hossain.dev
  • artifactId: json5kt
  • version: 1.0.0
• Set up GitHub Packages repository with proper authentication handling
• Added sources JAR generation for better developer experience
• Included comprehensive POM metadata:
  • Project name, description, and URL
  • MIT license information
  • Developer information
  • SCM (source control) details
• Updated README with installation instructions and authentication setup

Publishing Tasks Available

After these changes, the following publishing tasks are now available:

# Publish to local Maven repository (for testing)
./gradlew lib:publishToMavenLocal

# Publish to GitHub Packages
./gradlew lib:publishAllPublicationsToGitHubPackagesRepository

Usage

Once published, the library can be consumed by adding the GitHub Packages repository and dependency:

repositories {
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/hossain-khan/json5-kotlin")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
        }
    }
}

dependencies {
    implementation("hossain.dev:json5kt:1.0.0")
}

Testing

• ✅ Build and tests continue to pass
• ✅ POM file generation works correctly
• ✅ Sources JAR is created
• ✅ Local publishing to Maven repository works
• ✅ All publishing tasks are available

Fixes #12.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[hossain-khan]

Okay! looks good, just need to add the workflow later.

[hossain-khan]

How do I trigger maven publish to github package using this definition. When would I do it - what is the best practices?

[hossain-khan]

To trigger publishing to GitHub Packages using this Gradle definition, you would use the following command from your terminal in the project root:

./gradlew publish

This command will execute the publishing block defined in your build.gradle.kts file and upload your artifact (including your main JAR and sources JAR) to the GitHub Packages Maven repository specified in the configuration.

How Authentication Works

• The credentials for GitHub Packages (username and password/token) are read from Gradle properties (gpr.user and gpr.key) or environment variables (USERNAME and TOKEN).
• For best security and automation, set your TOKEN environment variable to a GitHub personal access token (with write:packages and read:packages scope).

When and How to Publish (Best Practices)

1. Release Process:

   • Only publish on release branches or tags, not for every commit.
   • Consider automating with GitHub Actions—trigger on push to main, master, or tag creation.

2. Version Management:

   • Update the version field in your publishing configuration to reflect semantic versioning and avoid overwriting packages.

3. CI/CD Automation:

   • Use GitHub Actions to run ./gradlew publish after running tests and checks.
   • Store your GitHub token as a secret in your repository, and use it in your workflow.

   Example GitHub Actions step:

   - name: Publish to GitHub Packages
     run: ./gradlew publish
     env:
       USERNAME: ${{ github.actor }}
       TOKEN: ${{ secrets.GITHUB_TOKEN }}

4. Local Publishing (for testing):

   • You can run ./gradlew publish locally with your environment variables set to test the process.

Recap

• Trigger publishing: ./gradlew publish
• Best time to publish: after successful tests, typically on release/tag commits
• Automate with CI/CD for consistency and reliability
• Manage authentication via environment variables or secrets

Let me know if you want an example workflow file or more details!

[hossain-khan]

Yes, Please provide example workflow

[hossain-khan]

Certainly! Here is an example GitHub Actions workflow to publish your Maven package to GitHub Packages using the Gradle configuration you provided.

Save this as .github/workflows/publish.yml in your repository:

name: Publish to GitHub Packages

on:
  push:
    tags:
      - 'v*'   # Triggers on version tags like v1.0.0
  workflow_dispatch:  # Allows manual trigger

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'    # Match your project's Java version

      - name: Cache Gradle packages
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

      - name: Grant execute permission for Gradle wrapper
        run: chmod +x ./gradlew

      - name: Publish to GitHub Packages
        env:
          USERNAME: ${{ github.actor }}
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: ./gradlew publish

How this works:

• Triggers when you push a tag like v1.0.0, or manually.
• Checks out code, sets up Java, and prepares Gradle.
• Runs ./gradlew publish, using the built-in GITHUB_TOKEN for authentication.

Best Practices:

• Only publish on tags to avoid pushing development versions.
• Use semantic versioning in your tags (e.g. v1.2.3).
• Optionally, restrict publishing to main or release branches if preferred.

Let me know if you want it to also publish on branch pushes, or if you need help customizing further!