Skip to content

Commit e19e0ac

Browse files
miserix13miserix13
committed
Enhance README.md with NuGet badges and add PUBLISHING.md for publishing guidelines
1 parent 0910a43 commit e19e0ac

5 files changed

Lines changed: 327 additions & 0 deletions

File tree

‎.github/PUBLISHING_QUICK_GUIDE.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Quick Publishing Guide
2+
3+
## 🚀 Quick Start
4+
5+
1. **One-time setup**: Add your NuGet API key to repository secrets
6+
```
7+
Settings → Secrets and variables → Actions → New repository secret
8+
Name: NUGET_API_KEY
9+
Value: [Your NuGet API key from nuget.org]
10+
```
11+
12+
2. **Publish a new version**:
13+
```bash
14+
git tag v1.0.0
15+
git push origin v1.0.0
16+
```
17+
18+
That's it! The GitHub Action will automatically build, test, and publish.
19+
20+
## 📋 Checklist Before Publishing
21+
22+
- [ ] All tests pass locally (`dotnet test`)
23+
- [ ] Version number follows semantic versioning
24+
- [ ] CHANGELOG updated (if applicable)
25+
- [ ] README is up to date
26+
- [ ] No breaking changes without major version bump
27+
28+
## 🔢 Version Numbers
29+
30+
- `v1.0.0` → First stable release
31+
- `v1.1.0` → New features added
32+
- `v1.1.1` → Bug fixes
33+
- `v2.0.0` → Breaking changes
34+
35+
## 📦 What Gets Published
36+
37+
- NuGet package (`.nupkg`)
38+
- Debug symbols (`.snupkg`)
39+
- README included in package
40+
- All three implementations: DuckDB, FastDB, LiteDB
41+
42+
## 🔗 Links
43+
44+
- **NuGet.org**: https://www.nuget.org/packages/WebNet.LiteGraphExtensions.GraphRepositories
45+
- **GitHub Releases**: Check the Releases tab for all versions
46+
- **Full Documentation**: See [PUBLISHING.md](PUBLISHING.md)
47+
48+
## ⚡ Manual Trigger
49+
50+
If you need to publish without creating a tag:
51+
1. Go to Actions tab
52+
2. Select "Publish NuGet Package"
53+
3. Click "Run workflow"
54+
4. Enter version (e.g., `1.0.1`)
55+
5. Click "Run workflow"

‎.github/workflows/publish-nuget.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: Publish NuGet Package
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*' # Triggers on version tags like v1.0.0, v2.1.3, etc.
7+
workflow_dispatch: # Allows manual triggering from GitHub UI
8+
inputs:
9+
version:
10+
description: 'Package version (e.g., 1.0.0)'
11+
required: true
12+
type: string
13+
14+
env:
15+
DOTNET_VERSION: '10.0.x'
16+
PROJECT_PATH: 'WebNet.LiteGraphExtensions.GraphRepositories.csproj'
17+
NUGET_SOURCE: 'https://api.nuget.org/v3/index.json'
18+
19+
jobs:
20+
build-and-publish:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout code
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0 # Get full history for versioning
28+
29+
- name: Setup .NET
30+
uses: actions/setup-dotnet@v4
31+
with:
32+
dotnet-version: ${{ env.DOTNET_VERSION }}
33+
34+
- name: Extract version from tag
35+
id: get_version
36+
run: |
37+
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
38+
VERSION="${{ github.event.inputs.version }}"
39+
else
40+
VERSION=${GITHUB_REF#refs/tags/v}
41+
fi
42+
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
43+
echo "Package version: $VERSION"
44+
45+
- name: Restore dependencies
46+
run: dotnet restore ${{ env.PROJECT_PATH }}
47+
48+
- name: Build
49+
run: dotnet build ${{ env.PROJECT_PATH }} --configuration Release --no-restore
50+
51+
- name: Run tests
52+
run: dotnet test --configuration Release --no-build --verbosity normal
53+
54+
- name: Pack NuGet package
55+
run: |
56+
dotnet pack ${{ env.PROJECT_PATH }} \
57+
--configuration Release \
58+
--no-build \
59+
--output ./artifacts \
60+
-p:PackageVersion=${{ steps.get_version.outputs.VERSION }} \
61+
-p:RepositoryUrl=${{ github.server_url }}/${{ github.repository }} \
62+
-p:RepositoryCommit=${{ github.sha }}
63+
64+
- name: List artifacts
65+
run: ls -la ./artifacts
66+
67+
- name: Publish to NuGet.org
68+
run: |
69+
dotnet nuget push ./artifacts/*.nupkg \
70+
--api-key ${{ secrets.NUGET_API_KEY }} \
71+
--source ${{ env.NUGET_SOURCE }} \
72+
--skip-duplicate
73+
74+
- name: Upload artifacts
75+
uses: actions/upload-artifact@v4
76+
with:
77+
name: nuget-package
78+
path: ./artifacts/*.nupkg
79+
retention-days: 30
80+
81+
- name: Create GitHub Release
82+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
83+
uses: softprops/action-gh-release@v1
84+
with:
85+
files: ./artifacts/*.nupkg
86+
generate_release_notes: true
87+
env:
88+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎PUBLISHING.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Publishing to NuGet
2+
3+
This repository includes a GitHub Action workflow that automatically builds, tests, and publishes the NuGet package.
4+
5+
## Prerequisites
6+
7+
1. **NuGet API Key**: You need to create an API key from [NuGet.org](https://www.nuget.org/account/apikeys)
8+
2. **GitHub Secret**: Add your NuGet API key as a repository secret:
9+
- Go to repository Settings → Secrets and variables → Actions
10+
- Click "New repository secret"
11+
- Name: `NUGET_API_KEY`
12+
- Value: Your NuGet API key
13+
14+
## Publishing Methods
15+
16+
### Method 1: Automatic Publishing via Git Tags (Recommended)
17+
18+
The workflow automatically triggers when you push a version tag:
19+
20+
```bash
21+
# Create and push a version tag
22+
git tag v1.0.0
23+
git push origin v1.0.0
24+
25+
# Or create with annotation
26+
git tag -a v1.0.0 -m "Release version 1.0.0"
27+
git push origin v1.0.0
28+
```
29+
30+
The workflow will:
31+
- Extract version from the tag (e.g., `v1.0.0` → `1.0.0`)
32+
- Build and test the project
33+
- Create NuGet package with the version
34+
- Publish to NuGet.org
35+
- Create a GitHub Release with the package attached
36+
37+
### Method 2: Manual Publishing via GitHub UI
38+
39+
You can manually trigger the workflow from GitHub:
40+
41+
1. Go to repository → Actions → "Publish NuGet Package"
42+
2. Click "Run workflow"
43+
3. Enter the version number (e.g., `1.0.1`)
44+
4. Click "Run workflow"
45+
46+
## Version Numbering
47+
48+
Follow [Semantic Versioning](https://semver.org/):
49+
- **MAJOR.MINOR.PATCH** (e.g., 1.2.3)
50+
- **MAJOR**: Breaking changes
51+
- **MINOR**: New features (backward compatible)
52+
- **PATCH**: Bug fixes (backward compatible)
53+
54+
Examples:
55+
- `v1.0.0` - Initial release
56+
- `v1.1.0` - Added new feature
57+
- `v1.1.1` - Bug fix
58+
- `v2.0.0` - Breaking changes
59+
60+
## Testing Before Publishing
61+
62+
Always test the package build locally before publishing:
63+
64+
```bash
65+
# Build the project
66+
dotnet build --configuration Release
67+
68+
# Run tests
69+
dotnet test --configuration Release
70+
71+
# Create package (without publishing)
72+
dotnet pack --configuration Release --output ./artifacts
73+
74+
# Inspect the package
75+
unzip -l ./artifacts/WebNet.LiteGraphExtensions.GraphRepositories.*.nupkg
76+
```
77+
78+
## Workflow Details
79+
80+
The GitHub Action workflow (`publish-nuget.yml`) performs these steps:
81+
82+
1. **Checkout**: Gets the repository code
83+
2. **Setup .NET**: Installs .NET 10.0
84+
3. **Extract Version**: Gets version from tag or input
85+
4. **Restore**: Restores NuGet dependencies
86+
5. **Build**: Builds in Release configuration
87+
6. **Test**: Runs all unit tests
88+
7. **Pack**: Creates NuGet package with metadata
89+
8. **Publish**: Pushes to NuGet.org
90+
9. **Artifacts**: Uploads package to GitHub
91+
10. **Release**: Creates GitHub release (for tag pushes)
92+
93+
## Package Metadata
94+
95+
The package includes:
96+
- **PackageId**: WebNet.LiteGraphExtensions.GraphRepositories
97+
- **Title**: LiteGraph Repository Extensions
98+
- **Description**: Full implementation descriptions
99+
- **Tags**: litegraph, graph, database, repository, duckdb, fastdb, litedb
100+
- **License**: MIT
101+
- **README**: Included in package
102+
- **Symbols**: Debug symbols included (.snupkg)
103+
104+
## Troubleshooting
105+
106+
### Build Fails
107+
- Ensure all tests pass locally
108+
- Check .NET version compatibility
109+
- Verify all dependencies are restored
110+
111+
### Authentication Fails
112+
- Verify `NUGET_API_KEY` secret is set correctly
113+
- Check API key hasn't expired on NuGet.org
114+
- Ensure API key has "Push" permissions
115+
116+
### Version Already Exists
117+
- NuGet doesn't allow overwriting versions
118+
- Increment the version number
119+
- Delete the tag and recreate with new version
120+
121+
### Package Not Appearing
122+
- NuGet indexing can take 10-15 minutes
123+
- Check workflow logs for errors
124+
- Verify package passed validation
125+
126+
## Updating Package
127+
128+
To publish an update:
129+
130+
```bash
131+
# Make your changes
132+
git add .
133+
git commit -m "Your changes"
134+
git push
135+
136+
# Create new version tag
137+
git tag v1.0.1
138+
git push origin v1.0.1
139+
```
140+
141+
## Rolling Back
142+
143+
If you need to unlist a version:
144+
145+
1. Go to [NuGet.org](https://www.nuget.org/)
146+
2. Find your package
147+
3. Select the version
148+
4. Click "Unlist"
149+
150+
Note: Unlisted packages can still be installed if version is specified explicitly.
151+
152+
## GitHub Release
153+
154+
Each tagged release creates a GitHub Release with:
155+
- Release notes (auto-generated from commits)
156+
- NuGet package (.nupkg) attached
157+
- Symbols package (.snupkg) attached
158+
159+
View releases at: `https://github.com/YOUR_USERNAME/WebNet.LiteGraphExtensions.GraphRepositories/releases`

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# WebNet.LiteGraphExtensions.GraphRepositories
22

3+
[![NuGet Version](https://img.shields.io/nuget/v/WebNet.LiteGraphExtensions.GraphRepositories.svg)](https://www.nuget.org/packages/WebNet.LiteGraphExtensions.GraphRepositories)
4+
[![NuGet Downloads](https://img.shields.io/nuget/dt/WebNet.LiteGraphExtensions.GraphRepositories.svg)](https://www.nuget.org/packages/WebNet.LiteGraphExtensions.GraphRepositories)
5+
[![Build Status](https://img.shields.io/github/actions/workflow/status/jojodev1/WebNet.LiteGraphExtensions.GraphRepositories/publish-nuget.yml?branch=main)](https://github.com/jojodev1/WebNet.LiteGraphExtensions.GraphRepositories/actions)
6+
[![License](https://img.shields.io/github/license/jojodev1/WebNet.LiteGraphExtensions.GraphRepositories.svg)](LICENSE.txt)
7+
38
Graph repository implementations for the LiteGraph library, providing persistent storage backends for graph data structures.
49

510
## Quick Start

‎WebNet.LiteGraphExtensions.GraphRepositories.csproj‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,28 @@
55
<ImplicitUsings>enable</ImplicitUsings>
66
<Nullable>enable</Nullable>
77
<DefaultItemExcludes>$(DefaultItemExcludes);Tests\**</DefaultItemExcludes>
8+
9+
<!-- NuGet Package Metadata -->
10+
<PackageId>WebNet.LiteGraphExtensions.GraphRepositories</PackageId>
11+
<Title>LiteGraph Repository Extensions</Title>
12+
<Description>Graph repository implementations for the LiteGraph library. Provides persistent storage backends including DuckDB (SQL/columnar), FastDB (NoSQL/collections), and LiteDB (NoSQL/documents) for graph data structures.</Description>
13+
<Authors>WebNet</Authors>
14+
<Company>WebNet</Company>
15+
<PackageTags>litegraph;graph;database;repository;duckdb;fastdb;litedb;nosql;sql;graph-database</PackageTags>
16+
<PackageLicenseExpression>MIT</PackageLicenseExpression>
17+
<PackageProjectUrl>https://github.com/jojodev1/WebNet.LiteGraphExtensions.GraphRepositories</PackageProjectUrl>
18+
<RepositoryUrl>https://github.com/jojodev1/WebNet.LiteGraphExtensions.GraphRepositories</RepositoryUrl>
19+
<RepositoryType>git</RepositoryType>
20+
<PackageReadmeFile>README.md</PackageReadmeFile>
21+
<GeneratePackageOnBuild>false</GeneratePackageOnBuild>
22+
<IncludeSymbols>true</IncludeSymbols>
23+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
824
</PropertyGroup>
925

26+
<ItemGroup>
27+
<None Include="README.md" Pack="true" PackagePath="\" />
28+
</ItemGroup>
29+
1030
<ItemGroup>
1131
<PackageReference Include="DuckDB.NET.Data.Full" Version="1.4.3" />
1232
<PackageReference Include="LiteDB" Version="5.0.21" />

0 commit comments

Comments
 (0)