diff --git a/.github/NUGET_SETUP.md b/.github/NUGET_SETUP.md new file mode 100644 index 0000000..0f70d26 --- /dev/null +++ b/.github/NUGET_SETUP.md @@ -0,0 +1,33 @@ +# NuGet Package Publishing Setup + +This document describes the one-time setup required to enable automated NuGet package publishing. + +## Required Setup + +### 1. Create a NuGet.org Account + +### 2. Generate a NuGet API Key + +1. Sign in to https://www.nuget.org/ +2. Go to your account settings: https://www.nuget.org/account/apikeys +3. Click "Create" +4. Configure the API key: + - **Select Packages**: Choose "Glob Pattern" + - **Glob Pattern**: Enter `PbfLite*` to restrict to PbfLite packages only +5. Click "Create" + +### 3. Add API Key to GitHub Secrets + +1. Go to your GitHub repository: https://github.com/lukaskabrt/PbfLITE +2. Navigate to Settings → Secrets and variables → Actions +3. Click "New repository secret" +4. Configure the secret: + - **Name**: `NUGET_API_KEY` (must match exactly) + - **Value**: Paste the API key you copied from NuGet.org +5. Click "Add secret" + +## Additional Resources + +- [NuGet API Keys Documentation](https://docs.microsoft.com/en-us/nuget/nuget-org/publish-a-package#managing-api-keys) +- [GitHub Secrets Documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets) +- [PbfLite Release Process](../RELEASING.md) diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 849936f..5719ae8 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -25,3 +25,6 @@ jobs: - name: Run tests run: dotnet test src/PbfLite.slnx --no-build --configuration Release --verbosity normal + + - name: Pack NuGet package + run: dotnet pack src/PbfLite/PbfLite.csproj --no-build --configuration Release --output ./nupkg diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..18ddecb --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,34 @@ +name: Release + +on: + push: + tags: + - 'v*.*.*' + +jobs: + release: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '8.0.x' + + - name: Restore dependencies + run: dotnet restore src/PbfLite.slnx + + - name: Build solution + run: dotnet build src/PbfLite.slnx --no-restore --configuration Release + + - name: Run tests + run: dotnet test src/PbfLite.slnx --no-build --configuration Release --verbosity normal + + - name: Pack NuGet package + run: dotnet pack src/PbfLite/PbfLite.csproj --no-build --configuration Release --output ./nupkg + + - name: Push to NuGet + run: dotnet nuget push ./nupkg/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate \ No newline at end of file diff --git a/.gitignore b/.gitignore index 31977c7..850d209 100644 --- a/.gitignore +++ b/.gitignore @@ -160,6 +160,7 @@ PublishScripts/ # NuGet Packages *.nupkg +nupkg/ # The packages folder can be ignored because of Package Restore **/packages/* # except build/, which is used as an MSBuild target. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..fe8592a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,16 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - TBD + +### Added +- Initial release of PbfLite + +[Unreleased]: https://github.com/lukaskabrt/PbfLITE/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/lukaskabrt/PbfLITE/releases/tag/v0.1.0 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5cd96b7 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Lukas Kabrt + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 68199c3..fdb646e 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,23 @@ PbfLITE is a low-level .NET Protocol Buffers implementation. It is intended for ## Getting Started -Add a reference to the `PbfLite` project and start using `PbfBlockReader` and `PbfBlockWriter` for manual protobuf serialization and deserialization. +### Installation + +Install PbfLite via NuGet: + +```bash +dotnet add package PbfLite +``` + +Or via the NuGet Package Manager: + +``` +Install-Package PbfLite +``` + +### Usage + +Start using `PbfBlockReader` and `PbfBlockWriter` for manual protobuf serialization and deserialization. ## Example: Deserializing an AddressBook diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..197ac46 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,106 @@ +# Release Process + +This document describes how to create a new release of PbfLite. + +## Versioning Strategy + +PbfLite follows [Semantic Versioning](https://semver.org/): + +- **MAJOR** version: incompatible API changes +- **MINOR** version: new functionality in a backward-compatible manner +- **PATCH** version: backward-compatible bug fixes + +Version is manually updated in `src/PbfLite/PbfLite.csproj` in the `` property. + +## Release Steps + +### 1. Prepare the Release + +1. Create a new branch for the release: + ```bash + git checkout -b release/vX.Y.Z + ``` + +2. Update the version in `src/PbfLite/PbfLite.csproj`: + ```xml + X.Y.Z + ``` + +3. Update `CHANGELOG.md`: + - Move items from `[Unreleased]` to a new `[X.Y.Z]` section + - Add the release date + - Update the comparison links at the bottom + +4. Commit the changes: + ```bash + git add src/PbfLite/PbfLite.csproj CHANGELOG.md + git commit -m "Prepare release vX.Y.Z" + ``` + +5. Push the branch and create a Pull Request: + ```bash + git push origin release/vX.Y.Z + ``` + +6. Wait for PR validation to pass and get approval + +7. Merge the PR to master + +### 2. Create and Push the Release Tag + +1. After the PR is merged, checkout and update master: + ```bash + git checkout master + git pull origin master + ``` + +2. Create an annotated tag: + ```bash + git tag -a vX.Y.Z -m "Release version X.Y.Z" + ``` + +3. Push the tag to GitHub: + ```bash + git push origin vX.Y.Z + ``` + +### 3. Automated Release Process + +Once the tag is pushed, the release workflow (`.github/workflows/release.yml`) will automatically: + +1. Build the project in Release configuration +2. Run all tests +3. Pack the NuGet package +4. Publish to NuGet.org + +## Tag Naming Convention + +Tags must follow the format `vX.Y.Z` where: +- `v` is a literal prefix +- `X.Y.Z` is the semantic version number + +## Release Notes Template + +When updating CHANGELOG.md, use the following structure: + +```markdown +## [X.Y.Z] - YYYY-MM-DD + +### Added +- New features + +### Changed +- Changes to existing functionality + +### Deprecated +- Features that will be removed in upcoming releases + +### Removed +- Removed features + +### Fixed +- Bug fixes + +### Security +- Security fixes +``` \ No newline at end of file diff --git a/src/PbfLite/PbfLite.csproj b/src/PbfLite/PbfLite.csproj index 954372c..8ea251a 100644 --- a/src/PbfLite/PbfLite.csproj +++ b/src/PbfLite/PbfLite.csproj @@ -2,6 +2,19 @@ net8.0 + + + PbfLite + 0.1.0 + Lukas Kabrt + PbfLITE is a low-level .NET Protocol Buffers implementation. It is intended for scenarios where you need fine-grained control over serialization and deserialization without the overhead of reflection, but it requires developers to manually implement the serialization / deserialization logic. + MIT + https://github.com/lukaskabrt/PbfLITE + https://github.com/lukaskabrt/PbfLITE + git + protobuf;protocol-buffers;serialization + README.md + false @@ -14,4 +27,8 @@ true + + + +