Skip to content

Commit 841cbf6

Browse files
ptthanh02ptthanh02
committed
add: add usage examples and GitHub workflows documentation for PluginLangCore
1 parent 980ef7f commit 841cbf6

5 files changed

Lines changed: 1181 additions & 0 deletions

File tree

‎.github/workflows/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# GitHub Workflows
2+
3+
This directory contains automated workflows for the PluginLangCore project.
4+
5+
## Workflows
6+
7+
### 1. Release Workflow (`release.yml`)
8+
9+
**Trigger:** Automatically runs on push to `main` or `master` branch, or can be triggered manually.
10+
11+
**What it does:**
12+
1. Extracts the version from `build.gradle`
13+
2. Checks if a tag with that version already exists
14+
3. If the tag doesn't exist:
15+
- Builds the project with Gradle
16+
- Creates a Git tag (e.g., `v1.0.0`)
17+
- Creates a GitHub Release with all built artifacts:
18+
- Main JAR
19+
- Sources JAR
20+
- Javadoc JAR
21+
4. If the tag exists, skips the release process
22+
23+
**Usage:**
24+
- Simply push your changes to the main branch
25+
- Or trigger manually from the Actions tab
26+
27+
### 2. Version Bump Workflow (`version-bump.yml`)
28+
29+
**Trigger:** Manual workflow dispatch with version input.
30+
31+
**What it does:**
32+
1. Updates the version in `build.gradle`
33+
2. Commits and pushes the change
34+
3. Automatically triggers the release workflow
35+
36+
**Usage:**
37+
1. Go to the Actions tab in your GitHub repository
38+
2. Select "Version Bump" workflow
39+
3. Click "Run workflow"
40+
4. Enter the new version (e.g., `1.0.1`, `1.1.0`, `2.0.0`)
41+
5. Click "Run workflow" button
42+
43+
## Workflow Process
44+
45+
### Automatic Release Process:
46+
```
47+
Change version in build.gradle → Commit & Push → Release workflow runs → Tag & Release created
48+
```
49+
50+
### Manual Version Bump Process:
51+
```
52+
Run Version Bump workflow → Enter new version → Version updated & committed → Release workflow runs → Tag & Release created
53+
```
54+
55+
## Important Notes
56+
57+
1. **Duplicate Releases:** The workflow checks if a tag already exists to prevent duplicate releases.
58+
59+
2. **Permissions:** The workflows use `GITHUB_TOKEN` which is automatically provided by GitHub Actions. Make sure your repository settings allow GitHub Actions to create releases.
60+
61+
3. **Branch Protection:** If you have branch protection rules, you may need to allow the GitHub Actions bot to push to the protected branch.
62+
63+
4. **Version Format:** Keep the version format consistent in `build.gradle`:
64+
```groovy
65+
version = '1.0.0'
66+
```
67+
68+
## Troubleshooting
69+
70+
### Workflow doesn't trigger
71+
- Check if the workflow file is on the correct branch (`main` or `master`)
72+
- Verify repository settings allow GitHub Actions
73+
74+
### Can't create tags or releases
75+
- Go to Settings → Actions → General → Workflow permissions
76+
- Select "Read and write permissions"
77+
- Check "Allow GitHub Actions to create and approve pull requests"
78+
79+
### Version not extracted correctly
80+
- Ensure the version line in `build.gradle` follows the exact format:
81+
```groovy
82+
version = '1.0.0'
83+
```
84+
(Single quotes, no extra spaces)
85+
86+
## Examples
87+
88+
### Example 1: Regular Release
89+
1. Update version in `build.gradle` to `1.0.1`
90+
2. Commit: `git commit -am "chore: bump version to 1.0.1"`
91+
3. Push: `git push`
92+
4. Workflow automatically creates tag `v1.0.1` and release
93+
94+
### Example 2: Using Version Bump Workflow
95+
1. Go to Actions → Version Bump → Run workflow
96+
2. Enter version: `1.1.0`
97+
3. Workflow updates `build.gradle`, commits, and triggers release
98+
99+
### Example 3: Manual Trigger
100+
1. Go to Actions → Create Release → Run workflow
101+
2. Select branch
102+
3. Run workflow (uses current version in `build.gradle`)
103+

‎.github/workflows/release.yml‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
name: Create Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
workflow_dispatch:
9+
10+
jobs:
11+
release:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: write
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Set up JDK 21
23+
uses: actions/setup-java@v4
24+
with:
25+
java-version: '21'
26+
distribution: 'temurin'
27+
28+
- name: Setup Gradle
29+
uses: gradle/actions/setup-gradle@v3
30+
31+
- name: Extract version from build.gradle
32+
id: get_version
33+
run: |
34+
VERSION=$(grep "^version = " build.gradle | sed "s/version = '\(.*\)'/\1/")
35+
echo "version=$VERSION" >> $GITHUB_OUTPUT
36+
echo "Extracted version: $VERSION"
37+
38+
- name: Check if tag exists
39+
id: check_tag
40+
run: |
41+
if git rev-parse "v${{ steps.get_version.outputs.version }}" >/dev/null 2>&1; then
42+
echo "exists=true" >> $GITHUB_OUTPUT
43+
echo "Tag v${{ steps.get_version.outputs.version }} already exists"
44+
else
45+
echo "exists=false" >> $GITHUB_OUTPUT
46+
echo "Tag v${{ steps.get_version.outputs.version }} does not exist"
47+
fi
48+
49+
- name: Build with Gradle
50+
if: steps.check_tag.outputs.exists == 'false'
51+
run: ./gradlew clean build
52+
53+
- name: Create Git Tag
54+
if: steps.check_tag.outputs.exists == 'false'
55+
run: |
56+
git config user.name "github-actions[bot]"
57+
git config user.email "github-actions[bot]@users.noreply.github.com"
58+
git tag -a "v${{ steps.get_version.outputs.version }}" -m "Release version ${{ steps.get_version.outputs.version }}"
59+
git push origin "v${{ steps.get_version.outputs.version }}"
60+
61+
- name: Create GitHub Release
62+
if: steps.check_tag.outputs.exists == 'false'
63+
uses: softprops/action-gh-release@v1
64+
with:
65+
tag_name: v${{ steps.get_version.outputs.version }}
66+
name: Release v${{ steps.get_version.outputs.version }}
67+
body: |
68+
## PluginLangCore v${{ steps.get_version.outputs.version }}
69+
70+
### 📦 Artifacts
71+
- Main JAR: `PluginLangCore-${{ steps.get_version.outputs.version }}.jar`
72+
- Sources JAR: `PluginLangCore-${{ steps.get_version.outputs.version }}-sources.jar`
73+
- Javadoc JAR: `PluginLangCore-${{ steps.get_version.outputs.version }}-javadoc.jar`
74+
75+
### 📚 Documentation
76+
See [README.md](https://github.com/${{ github.repository }}/blob/main/README.md) for usage instructions.
77+
78+
### 🔗 Maven Dependency
79+
```xml
80+
<dependency>
81+
<groupId>io.github.pluginlangcore</groupId>
82+
<artifactId>pluginlangcore</artifactId>
83+
<version>${{ steps.get_version.outputs.version }}</version>
84+
</dependency>
85+
```
86+
87+
### 🔗 Gradle Dependency
88+
```groovy
89+
implementation 'io.github.pluginlangcore:pluginlangcore:${{ steps.get_version.outputs.version }}'
90+
```
91+
draft: false
92+
prerelease: false
93+
files: |
94+
build/libs/*.jar
95+
env:
96+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
97+
98+
- name: Skip release
99+
if: steps.check_tag.outputs.exists == 'true'
100+
run: echo "Release v${{ steps.get_version.outputs.version }} already exists, skipping..."
101+

‎.github/workflows/version-bump.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Version Bump
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version:
7+
description: 'New version (e.g., 1.0.1, 1.1.0, 2.0.0)'
8+
required: true
9+
type: string
10+
11+
jobs:
12+
bump-version:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: write
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
with:
21+
token: ${{ secrets.GITHUB_TOKEN }}
22+
23+
- name: Update version in build.gradle
24+
run: |
25+
sed -i "s/^version = '.*'/version = '${{ github.event.inputs.version }}'/" build.gradle
26+
cat build.gradle | grep "^version = "
27+
28+
- name: Commit version bump
29+
run: |
30+
git config user.name "github-actions[bot]"
31+
git config user.email "github-actions[bot]@users.noreply.github.com"
32+
git add build.gradle
33+
git commit -m "chore: bump version to ${{ github.event.inputs.version }}"
34+
git push
35+
36+
- name: Trigger release workflow
37+
run: |
38+
echo "Version bumped to ${{ github.event.inputs.version }}"
39+
echo "The release workflow will be triggered automatically by the push event"
40+

0 commit comments

Comments
 (0)