Skip to content

Commit 4611b7e

Browse files
afarberafarber
committed
Publish to JitPack as well
1 parent 36fa1e0 commit 4611b7e

4 files changed

Lines changed: 599 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,16 @@
33
[![Release](https://github.com/afarber/OpenMapView/actions/workflows/release.yml/badge.svg)](https://github.com/afarber/OpenMapView/actions/workflows/release.yml)
44
[![codecov](https://codecov.io/gh/afarber/OpenMapView/branch/main/graph/badge.svg)](https://codecov.io/gh/afarber/OpenMapView)
55
[![Maven Central](https://img.shields.io/maven-central/v/de.afarber/openmapview.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/de.afarber/openmapview)
6+
[![JitPack](https://jitpack.io/v/afarber/OpenMapView.svg)](https://jitpack.io/#afarber/OpenMapView)
67

78
# OpenMapView
89

910
A modern, Kotlin-first MapView replacement for Android — powered by [OpenStreetMap](https://www.openstreetmap.org/).
1011

1112
## Installation
1213

14+
### Maven Central (Recommended)
15+
1316
Add the dependency to the module `build.gradle.kts`:
1417

1518
```kotlin
@@ -26,6 +29,48 @@ dependencies {
2629
}
2730
```
2831

32+
### JitPack (Alternative)
33+
34+
JitPack provides instant access to GitHub releases and supports development snapshots.
35+
36+
Add the JitPack repository in `settings.gradle.kts`:
37+
38+
```kotlin
39+
dependencyResolutionManagement {
40+
repositories {
41+
google()
42+
mavenCentral()
43+
maven { url = uri("https://jitpack.io") }
44+
}
45+
}
46+
```
47+
48+
Then add the dependency:
49+
50+
```kotlin
51+
dependencies {
52+
implementation("com.github.afarber:OpenMapView:0.1.0")
53+
}
54+
```
55+
56+
For Groovy `settings.gradle`:
57+
58+
```groovy
59+
dependencyResolutionManagement {
60+
repositories {
61+
google()
62+
mavenCentral()
63+
maven { url 'https://jitpack.io' }
64+
}
65+
}
66+
```
67+
68+
```groovy
69+
dependencies {
70+
implementation 'com.github.afarber:OpenMapView:0.1.0'
71+
}
72+
```
73+
2974
## Features
3075

3176
- Drop-in compatible with Google `MapView` (non-deprecated methods only)
@@ -60,7 +105,9 @@ Demonstrates marker system with custom icons and click handling.
60105

61106
- [Contributing Guide](docs/CONTRIBUTING.md) - Code quality requirements, formatting, git hooks, and PR process
62107
- [Lifecycle Management](docs/LIFECYCLE.md) - How OpenMapView handles Android lifecycle events
63-
- [Maven Central Setup](docs/MAVEN_CENTRAL_SETUP.md) - Publishing configuration and release process
108+
- [Publishing Guide](docs/PUBLISHING.md) - Publishing to Maven Central and JitPack
109+
- [Maven Central Setup](docs/MAVEN_CENTRAL_SETUP.md) - Detailed Maven Central configuration
110+
- [JitPack Setup](docs/JITPACK_SETUP.md) - Detailed JitPack configuration
64111
- [GitHub Workflows](docs/GITHUB_WORKFLOWS.md) - CI/CD pipeline and workflow architecture
65112
- [Unit Testing](docs/TESTING_UNIT.md) - JVM unit tests with Robolectric for Android framework APIs
66113
- [Instrumented Testing](docs/TESTING_INSTRUMENTED.md) - On-device (phone and auto) testing with Android emulator

‎docs/JITPACK_SETUP.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# JitPack Publishing Setup Guide
2+
3+
[Back to README](../README.md)
4+
5+
This guide documents the JitPack publishing setup for OpenMapView.
6+
7+
## Overview
8+
9+
JitPack is a package repository for Git repositories that automatically builds Maven/Gradle artifacts directly from GitHub releases and tags. It requires minimal configuration and provides instant publishing without manual uploads.
10+
11+
## Current Status
12+
13+
**Setup Complete** - OpenMapView is configured to publish to JitPack.
14+
15+
- **Group ID**: `com.github.afarber`
16+
- **Artifact ID**: `OpenMapView`
17+
- **Repository**: https://github.com/afarber/OpenMapView
18+
- **JitPack URL**: https://jitpack.io/#afarber/OpenMapView
19+
20+
## How JitPack Works
21+
22+
1. When a user requests a dependency, JitPack automatically:
23+
- Checks out the code from the specified release/tag/commit
24+
- Runs the build process
25+
- Caches the built artifacts
26+
- Serves the artifacts to Maven/Gradle clients
27+
28+
2. No manual publishing required - JitPack builds on demand from GitHub
29+
30+
3. Supports multiple artifact types:
31+
- Release versions (tags)
32+
- Snapshot builds (branches)
33+
- Specific commits
34+
35+
## Configuration
36+
37+
### jitpack.yml
38+
39+
The repository contains a `jitpack.yml` file that specifies the build environment:
40+
41+
```yaml
42+
jdk:
43+
- openjdk17
44+
```
45+
46+
This configuration is required because Android Gradle Plugin 8.7.0 requires Java 17.
47+
48+
### Build Configuration
49+
50+
JitPack uses the existing `maven-publish` plugin configuration in `openmapview/build.gradle.kts`. No additional setup is needed beyond what is already configured for Maven Central publishing.
51+
52+
## Usage for Users
53+
54+
### Adding JitPack Repository
55+
56+
Users need to add the JitPack repository to their project.
57+
58+
In `settings.gradle.kts`:
59+
60+
```kotlin
61+
dependencyResolutionManagement {
62+
repositories {
63+
google()
64+
mavenCentral()
65+
maven { url = uri("https://jitpack.io") }
66+
}
67+
}
68+
```
69+
70+
Or in Groovy `settings.gradle`:
71+
72+
```groovy
73+
dependencyResolutionManagement {
74+
repositories {
75+
google()
76+
mavenCentral()
77+
maven { url 'https://jitpack.io' }
78+
}
79+
}
80+
```
81+
82+
### Adding the Dependency
83+
84+
#### Release Version
85+
86+
To use a specific release (e.g., v0.1.0):
87+
88+
```kotlin
89+
dependencies {
90+
implementation("com.github.afarber:OpenMapView:0.1.0")
91+
}
92+
```
93+
94+
```groovy
95+
dependencies {
96+
implementation 'com.github.afarber:OpenMapView:0.1.0'
97+
}
98+
```
99+
100+
#### Latest Release
101+
102+
To always use the latest release:
103+
104+
```kotlin
105+
dependencies {
106+
implementation("com.github.afarber:OpenMapView:+")
107+
}
108+
```
109+
110+
#### Development Snapshots
111+
112+
To use the latest commit from the main branch:
113+
114+
```kotlin
115+
dependencies {
116+
implementation("com.github.afarber:OpenMapView:main-SNAPSHOT")
117+
}
118+
```
119+
120+
To use a specific commit:
121+
122+
```kotlin
123+
dependencies {
124+
implementation("com.github.afarber:OpenMapView:abc1234")
125+
}
126+
```
127+
128+
To use a specific branch:
129+
130+
```kotlin
131+
dependencies {
132+
implementation("com.github.afarber:OpenMapView:feature-branch-SNAPSHOT")
133+
}
134+
```
135+
136+
## Publishing Process
137+
138+
### For Maintainers
139+
140+
Publishing to JitPack is automatic and happens when users request the artifact:
141+
142+
1. **Create a GitHub Release** (or push a tag):
143+
```bash
144+
git tag v0.2.0
145+
git push origin v0.2.0
146+
```
147+
148+
2. **JitPack automatically**:
149+
- Detects the new tag
150+
- Builds the artifact on first request
151+
- Caches the build for future requests
152+
153+
3. **No manual upload required** - JitPack pulls directly from GitHub
154+
155+
### First Build
156+
157+
The first time a user requests a new version, JitPack builds it on-demand. This may take a few minutes. Subsequent requests are served from cache.
158+
159+
### Build Status
160+
161+
Check the build status at:
162+
```
163+
https://jitpack.io/#afarber/OpenMapView
164+
```
165+
166+
The JitPack website shows:
167+
- Available versions
168+
- Build status (success/failure)
169+
- Build logs
170+
- Download statistics
171+
172+
## Testing Locally
173+
174+
Before pushing a release, test that the library can be published to Maven Local:
175+
176+
```bash
177+
./gradlew publishToMavenLocal
178+
```
179+
180+
This ensures the build configuration is correct and JitPack will be able to build the artifact.
181+
182+
## Advantages of JitPack
183+
184+
1. **Zero Configuration** - Uses existing `maven-publish` setup
185+
2. **Instant Publishing** - No waiting for Maven Central sync
186+
3. **Development Snapshots** - Test unreleased versions from branches/commits
187+
4. **No Credentials Required** - Builds directly from public GitHub repository
188+
5. **Automatic Builds** - No manual upload process
189+
190+
## Comparison with Maven Central
191+
192+
| Feature | JitPack | Maven Central |
193+
|---------|---------|---------------|
194+
| Setup Complexity | Minimal | Moderate |
195+
| Publishing Speed | Instant | 10-30 minutes |
196+
| Snapshot Support | Yes (branches/commits) | No |
197+
| User Setup | Requires repository declaration | Works out-of-the-box |
198+
| Credential Management | None required | GPG signing + user tokens |
199+
| Discoverability | Lower | Higher |
200+
| Best For | Development/testing | Production releases |
201+
202+
## Troubleshooting
203+
204+
### Issue: Build fails on JitPack
205+
206+
**Solution:** Check the build logs at https://jitpack.io/#afarber/OpenMapView
207+
208+
Common issues:
209+
- Missing `jitpack.yml` with correct JDK version
210+
- Build configuration errors in `build.gradle.kts`
211+
- Missing dependencies or plugins
212+
213+
### Issue: Build succeeds but artifact is empty
214+
215+
**Solution:** Verify the `maven-publish` plugin is correctly configured:
216+
217+
```bash
218+
./gradlew publishToMavenLocal
219+
ls ~/.m2/repository/de/afarber/openmapview/
220+
```
221+
222+
### Issue: Users report "artifact not found"
223+
224+
**Solution:**
225+
- Ensure the repository is public on GitHub
226+
- Check that the tag/release exists
227+
- Verify the correct artifact coordinates are used:
228+
- Group: `com.github.afarber`
229+
- Artifact: `OpenMapView` (case-sensitive)
230+
231+
### Issue: Want to rebuild a version
232+
233+
**Solution:** Delete builds at https://jitpack.io/#afarber/OpenMapView using the "Look up" button and rebuild option.
234+
235+
## Version Numbering
236+
237+
JitPack uses Git tags for versioning:
238+
239+
- Tags like `v0.1.0` become version `0.1.0`
240+
- Tags like `0.1.0` also become version `0.1.0`
241+
- Branch `main` becomes `main-SNAPSHOT`
242+
- Specific commits use their SHA hash
243+
244+
## Resources
245+
246+
- **JitPack Website**: https://jitpack.io/
247+
- **JitPack Documentation**: https://docs.jitpack.io/
248+
- **Android Guide**: https://docs.jitpack.io/android/
249+
- **Build Status**: https://jitpack.io/#afarber/OpenMapView
250+
- **Example Android Project**: https://github.com/jitpack/android-example
251+
252+
## Quick Reference
253+
254+
```bash
255+
# Test local publishing
256+
./gradlew publishToMavenLocal
257+
258+
# Create a release (triggers JitPack availability)
259+
git tag v0.2.0
260+
git push origin v0.2.0
261+
262+
# Check build status
263+
# Visit: https://jitpack.io/#afarber/OpenMapView
264+
265+
# Users can install with:
266+
# implementation("com.github.afarber:OpenMapView:0.2.0")
267+
```
268+
269+
## Related Documentation
270+
271+
- [Publishing Overview](PUBLISHING.md) - Complete guide to Maven Central and JitPack publishing
272+
- [Maven Central Setup](MAVEN_CENTRAL_SETUP.md) - Maven Central specific configuration
273+
- [GitHub Workflows](GITHUB_WORKFLOWS.md) - CI/CD pipeline

0 commit comments

Comments
 (0)