Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,40 @@ JSON5 extends JSON with the following features:
Add the dependency to your `build.gradle.kts`:

```kotlin
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("io.github.json5:json5-kotlin:VERSION")
implementation("hossain.dev:json5kt:1.0.0")
}
```

### Authentication for GitHub Packages

To access GitHub Packages, you need to authenticate with GitHub. You can do this by:

1. **Using environment variables:**
```bash
export USERNAME=your_github_username
export TOKEN=your_github_personal_access_token
```

2. **Using gradle.properties:**
```properties
gpr.user=your_github_username
gpr.key=your_github_personal_access_token
```

You can generate a personal access token at [GitHub > Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens) with `read:packages` permission.

## Usage

### Basic Parsing and Stringifying
Expand Down
60 changes: 60 additions & 0 deletions lib/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ plugins {
id("buildsrc.convention.kotlin-jvm")
alias(libs.plugins.kover)
alias(libs.plugins.kotlinPluginSerialization)
`maven-publish`
}

dependencies {
Expand All @@ -21,3 +22,62 @@ dependencies {
tasks.test {
useJUnitPlatform()
}

// Configure JAR to include sources
val sourcesJar by tasks.registering(Jar::class) {
archiveClassifier.set("sources")
from(sourceSets.main.get().allSource)
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}

// Publishing configuration
publishing {
publications {
register<MavenPublication>("maven") {
groupId = "hossain.dev"
artifactId = "json5kt"
version = "1.0.0"

from(components["java"])
artifact(sourcesJar)

pom {
name.set("JSON5 Kotlin")
description.set("A robust JSON5 parser and serializer for Kotlin/JVM that extends JSON with helpful features like comments, trailing commas, and unquoted keys while maintaining full backward compatibility with JSON.")
url.set("https://github.com/hossain-khan/json5-kotlin")

licenses {
license {
name.set("MIT License")
url.set("https://opensource.org/licenses/MIT")
}
}

developers {
developer {
id.set("hossain-khan")
name.set("Hossain Khan")
email.set("[email protected]")
}
}

scm {
connection.set("scm:git:git://github.com/hossain-khan/json5-kotlin.git")
developerConnection.set("scm:git:ssh://github.com:hossain-khan/json5-kotlin.git")
url.set("https://github.com/hossain-khan/json5-kotlin")
}
}
}
}

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")
}
}
}
}
Comment on lines +25 to +83
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, Please provide example workflow

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!