Skip to content

Commit 7532247

Browse files
oexzaoexza
committed
docs: restructure installation guide to prioritize GitHub Packages
- Move GitHub Packages to primary installation method - Add authentication setup instructions for Maven and Gradle - Keep direct JAR download as secondary option - Simplify and clarify installation steps for both build tools - Automate README version updates during release process
1 parent b8a6f4a commit 7532247

2 files changed

Lines changed: 126 additions & 104 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,18 @@ jobs:
6262
- name: Grant execute permission for gradlew
6363
run: chmod +x gradlew
6464

65+
- name: Update README with release version
66+
run: |
67+
VERSION="${{ needs.validate.outputs.version }}"
68+
sed -i "s/<version>[^<]*<\/version>/<version>${VERSION}<\/version>/g" README.md
69+
sed -i "s/implementation '[^']*'/implementation 'com.orisunlabs:orisun-java-client:${VERSION}'/g" README.md
70+
sed -i 's/implementation "[^"]*"/implementation "com.orisunlabs:orisun-java-client:${VERSION}"/g' README.md
71+
git config user.name "github-actions[bot]"
72+
git config user.email "github-actions[bot]@users.noreply.github.com"
73+
git add README.md
74+
git commit -m "chore: update README to version ${VERSION}"
75+
git push
76+
6577
- name: Build release artifacts
6678
run: ./gradlew clean build shadowJar sourcesJar javadocJar
6779

@@ -184,79 +196,84 @@ jobs:
184196
185197
## Installation
186198
187-
Download the `orisun-java-client-${{ needs.validate.outputs.version }}.jar` file from the assets below.
199+
### Option 1: GitHub Packages (Recommended)
188200
189-
### Maven
201+
The client is published to GitHub Packages.
190202
191-
**Option 1: System dependency**
203+
**Maven**
192204
193-
Place the JAR in your project's `lib/` directory and add to `pom.xml`:
205+
Add to `pom.xml`:
194206
195207
```xml
196-
<dependency>
197-
<groupId>com.orisunlabs</groupId>
198-
<artifactId>orisun-java-client</artifactId>
199-
<version>${{ needs.validate.outputs.version }}</version>
200-
<scope>system</scope>
201-
<systemPath>${project.basedir}/lib/orisun-java-client-${{ needs.validate.outputs.version }}.jar</systemPath>
202-
</dependency>
208+
<repositories>
209+
<repository>
210+
<id>github</id>
211+
<url>https://maven.pkg.github.com/oexza/orisun-client-java</url>
212+
</repository>
213+
</repositories>
214+
215+
<dependencies>
216+
<dependency>
217+
<groupId>com.orisunlabs</groupId>
218+
<artifactId>orisun-java-client</artifactId>
219+
<version>${{ needs.validate.outputs.version }}</version>
220+
</dependency>
221+
</dependencies>
203222
```
204223
205-
**Option 2: Install to local Maven repository**
206-
207-
```bash
208-
mvn install:install-file \
209-
-Dfile=orisun-java-client-${{ needs.validate.outputs.version }}.jar \
210-
-DgroupId=com.orisunlabs \
211-
-DartifactId=orisun-java-client \
212-
-Dversion=${{ needs.validate.outputs.version }} \
213-
-Dpackaging=jar
214-
```
215-
216-
Then add as a regular dependency in `pom.xml`:
224+
Configure authentication in `~/.m2/settings.xml`:
217225
218226
```xml
219-
<dependency>
220-
<groupId>com.orisunlabs</groupId>
221-
<artifactId>orisun-java-client</artifactId>
222-
<version>${{ needs.validate.outputs.version }}</version>
223-
</dependency>
227+
<server>
228+
<id>github</id>
229+
<username>YOUR_GITHUB_USERNAME</username>
230+
<password>YOUR_GITHUB_TOKEN</password>
231+
</server>
224232
```
225233
226-
### Gradle
227-
228-
**Option 1: Direct file dependency**
234+
**Gradle**
229235
230-
Place the JAR in your project's `libs/` directory and add to `build.gradle`:
231-
232-
```groovy
233-
dependencies {
234-
implementation files("libs/orisun-java-client-${{ needs.validate.outputs.version }}.jar")
235-
}
236-
```
237-
238-
**Option 2: Flat directory repository**
236+
Add to `build.gradle`:
239237
240238
```groovy
241239
repositories {
242-
flatDir { dirs 'libs' }
240+
maven {
241+
url = 'https://maven.pkg.github.com/oexza/orisun-client-java'
242+
credentials {
243+
username = project.findProperty('githubUsername') ?: System.getenv('GITHUB_USERNAME')
244+
password = project.findProperty('githubToken') ?: System.getenv('GITHUB_TOKEN')
245+
}
246+
}
243247
}
244248
245249
dependencies {
246250
implementation "com.orisunlabs:orisun-java-client:${{ needs.validate.outputs.version }}"
247251
}
248252
```
249253
250-
**Option 3: Build from source**
254+
### Option 2: Download JAR
255+
256+
Download `orisun-java-client-${{ needs.validate.outputs.version }}.jar` from the assets below.
251257
252-
```bash
253-
git clone https://github.com/oexza/orisun-client-java.git
254-
cd orisun-client-java
255-
git submodule update --init --recursive
256-
./gradlew build
258+
**Maven - System dependency:**
259+
260+
```xml
261+
<dependency>
262+
<groupId>com.orisunlabs</groupId>
263+
<artifactId>orisun-java-client</artifactId>
264+
<version>${{ needs.validate.outputs.version }}</version>
265+
<scope>system</scope>
266+
<systemPath>${project.basedir}/lib/orisun-java-client-${{ needs.validate.outputs.version }}.jar</systemPath>
267+
</dependency>
257268
```
258269
259-
The JAR will be at: `build/libs/orisun-client-${{ needs.validate.outputs.version }}.jar`
270+
**Gradle - File dependency:**
271+
272+
```groovy
273+
dependencies {
274+
implementation files("libs/orisun-java-client-${{ needs.validate.outputs.version }}.jar")
275+
}
276+
```
260277
261278
## Usage
262279

‎README.md‎

Lines changed: 61 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -13,100 +13,105 @@ A Java client for the Orisun event store, providing a simple and intuitive inter
1313

1414
## Installation
1515

16-
### Download from GitHub Releases
16+
### Option 1: GitHub Packages (Recommended)
1717

18-
The latest release JAR (with all dependencies included) can be downloaded from the [Releases](https://github.com/oexza/orisun-client-java/releases) page.
18+
The client is published to GitHub Packages. To use it, you'll need to authenticate with your GitHub credentials.
1919

20-
Download the `orisun-java-client-{version}.jar` file and follow the instructions below for your build system.
20+
**Maven**
2121

22-
### Using in Your Project
23-
24-
#### Maven
25-
26-
1. Download the JAR file from the [Releases](https://github.com/oexza/orisun-client-java/releases) page
27-
2. Place the JAR in your project's `lib/` directory (or any directory you prefer)
28-
3. Add the following to your `pom.xml`:
22+
Add the GitHub Packages repository and dependency to your `pom.xml`:
2923

3024
```xml
25+
<repositories>
26+
<repository>
27+
<id>github</id>
28+
<url>https://maven.pkg.github.com/oexza/orisun-client-java</url>
29+
</repository>
30+
</repositories>
31+
3132
<dependencies>
3233
<dependency>
3334
<groupId>com.orisunlabs</groupId>
3435
<artifactId>orisun-java-client</artifactId>
3536
<version>0.0.1</version>
36-
<scope>system</scope>
37-
<systemPath>${project.basedir}/lib/orisun-java-client-0.0.1.jar</systemPath>
3837
</dependency>
3938
</dependencies>
4039
```
4140

42-
**Note**: Replace `0.0.1` with the actual version you downloaded and adjust the path if you placed the JAR in a different location.
41+
Configure authentication in your `~/.m2/settings.xml`:
4342

44-
Alternatively, you can install the JAR to your local Maven repository:
43+
```xml
44+
<server>
45+
<id>github</id>
46+
<username>YOUR_GITHUB_USERNAME</username>
47+
<password>YOUR_GITHUB_TOKEN</password>
48+
</server>
49+
```
4550

46-
```bash
47-
mvn install:install-file \
48-
-Dfile=orisun-java-client-0.0.1.jar \
49-
-DgroupId=com.orisunlabs \
50-
-DartifactId=orisun-java-client \
51-
-Dversion=0.0.1 \
52-
-Dpackaging=jar
51+
**Gradle**
52+
53+
Add to your `build.gradle`:
54+
55+
```groovy
56+
repositories {
57+
maven {
58+
url = 'https://maven.pkg.github.com/oexza/orisun-client-java'
59+
credentials {
60+
username = project.findProperty('githubUsername') ?: System.getenv('GITHUB_USERNAME')
61+
password = project.findProperty('githubToken') ?: System.getenv('GITHUB_TOKEN')
62+
}
63+
}
64+
}
65+
66+
dependencies {
67+
implementation 'com.orisunlabs:orisun-java-client:0.0.1'
68+
}
5369
```
5470

55-
Then add it as a regular dependency:
71+
Add credentials to `~/.gradle/gradle.properties`:
72+
73+
```properties
74+
githubUsername=YOUR_GITHUB_USERNAME
75+
githubToken=YOUR_GITHUB_TOKEN
76+
```
77+
78+
**Note**: You can create a GitHub personal access token at https://github.com/settings/tokens
79+
80+
### Option 2: Download from GitHub Releases
81+
82+
If you prefer not to use GitHub Packages, you can download the JAR directly from [Releases](https://github.com/oexza/orisun-client-java/releases).
83+
84+
Download the `orisun-java-client-{version}.jar` file and use one of the methods below.
85+
86+
#### Maven - System Dependency
87+
88+
Place the JAR in your project's `lib/` directory and add to `pom.xml`:
5689

5790
```xml
5891
<dependency>
5992
<groupId>com.orisunlabs</groupId>
6093
<artifactId>orisun-java-client</artifactId>
6194
<version>0.0.1</version>
95+
<scope>system</scope>
96+
<systemPath>${project.basedir}/lib/orisun-java-client-0.0.1.jar</systemPath>
6297
</dependency>
6398
```
6499

65-
#### Gradle
100+
#### Gradle - File Dependency
66101

67-
**Option 1: Direct file dependency**
68-
69-
1. Download the JAR file from the [Releases](https://github.com/oexza/orisun-client-java/releases) page
70-
2. Place the JAR in your project's `libs/` directory
71-
3. Add the following to your `build.gradle`:
102+
Place the JAR in your project's `libs/` directory and add to `build.gradle`:
72103

73104
```groovy
74105
dependencies {
75106
implementation files('libs/orisun-java-client-0.0.1.jar')
76107
}
77108
```
78109

79-
**Option 2: Flat directory repository**
80-
81-
1. Create a `libs/` directory in your project
82-
2. Place the JAR file in the `libs/` directory
83-
3. Add the following to your `build.gradle`:
84-
85-
```groovy
86-
repositories {
87-
flatDir {
88-
dirs 'libs'
89-
}
90-
}
91-
92-
dependencies {
93-
implementation 'com.orisunlabs:orisun-java-client:0.0.1'
94-
}
95-
```
96-
97-
**Option 3: Local Maven repository**
98-
99-
First, install the JAR to your local Maven repository:
100-
101-
```bash
102-
./gradlew publishToMavenLocal
103-
```
104-
105-
Then add it to your project's `build.gradle`:
110+
Or use a flat directory repository:
106111

107112
```groovy
108113
repositories {
109-
mavenLocal()
114+
flatDir { dirs 'libs' }
110115
}
111116
112117
dependencies {

0 commit comments

Comments
 (0)