Skip to content

Commit f021e04

Browse files
VanderhellVanderhell
committed
Prepare repository for GitHub
1 parent 66183cb commit f021e04

18 files changed

Lines changed: 640 additions & 13 deletions

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Bug report
2+
description: Report reproducible incorrect Basalt behavior
3+
title: "[Bug]: "
4+
labels: [bug]
5+
body:
6+
- type: input
7+
id: version
8+
attributes:
9+
label: Basalt commit or version
10+
placeholder: e.g. 66183cb or 1.0.0-rc.4
11+
validations:
12+
required: true
13+
- type: dropdown
14+
id: provider
15+
attributes:
16+
label: Storage provider
17+
options: [Embedded, SQL Server, Both, Not storage-specific]
18+
validations:
19+
required: true
20+
- type: input
21+
id: dotnet
22+
attributes:
23+
label: .NET version
24+
placeholder: e.g. .NET 8 or .NET Framework 4.7.2
25+
validations:
26+
required: true
27+
- type: input
28+
id: os
29+
attributes:
30+
label: Operating system
31+
validations:
32+
required: true
33+
- type: textarea
34+
id: reproduction
35+
attributes:
36+
label: Reproduction
37+
description: List the smallest reliable steps and include a minimal sample where possible.
38+
validations:
39+
required: true
40+
- type: textarea
41+
id: expected
42+
attributes:
43+
label: Expected result
44+
validations:
45+
required: true
46+
- type: textarea
47+
id: actual
48+
attributes:
49+
label: Actual result
50+
validations:
51+
required: true
52+
- type: textarea
53+
id: logs
54+
attributes:
55+
label: Logs or error
56+
description: Remove credentials and sensitive data before pasting output.
57+
render: text

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
blank_issues_enabled: false
2+
contact_links: []

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Feature request
2+
description: Propose a change based on a real use case
3+
title: "[Feature]: "
4+
labels: [enhancement]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: Problem or use case
10+
description: Describe the real application need rather than only a proposed API.
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: behavior
15+
attributes:
16+
label: Desired behavior
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: insufficient
21+
attributes:
22+
label: Why the current API is insufficient
23+
validations:
24+
required: true
25+
- type: dropdown
26+
id: component
27+
attributes:
28+
label: Affected provider or component
29+
options: [Managed API, Embedded, SQL Server, Scheduler, Workflows, Management, Documentation, Other]
30+
validations:
31+
required: true
32+
- type: textarea
33+
id: compatibility
34+
attributes:
35+
label: Compatibility implications
36+
description: Note public API, durable-format, deployment, or migration impact if known.

‎.github/pull_request_template.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## What changed
2+
3+
## Why
4+
5+
## Tests executed
6+
7+
## Documentation impact
8+
9+
## Public API compatibility
10+
11+
## Durable/persistence format impact

‎.github/workflows/ci.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
windows-fast-validation:
14+
runs-on: windows-latest
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
19+
- name: Set up .NET
20+
uses: actions/setup-dotnet@v4
21+
with:
22+
dotnet-version: 9.0.x
23+
24+
- name: Configure native build
25+
run: cmake -S . -B build -A x64
26+
27+
- name: Build native Core
28+
run: cmake --build build --config Debug
29+
30+
- name: Run fast native tests
31+
run: ctest --test-dir build -C Debug --output-on-failure -R "^(BasaltDB_tests|BasaltCore_tests|BasaltCore_scheduler_policy_tests|BasaltCore_worker_test|BasaltStorage_contract_tests)$"
32+
33+
- name: Build managed Core
34+
run: dotnet build BasaltCore/BasaltCore.csproj -c Debug
35+
36+
- name: Build SQL Server provider
37+
run: dotnet build BasaltCore.SqlServer/BasaltCore.SqlServer.csproj -c Debug
38+
39+
- name: Build and run modern Embedded consumer
40+
run: |
41+
dotnet build consumer-smoke/Consumer.csproj -c Debug
42+
dotnet run --project consumer-smoke/Consumer.csproj -c Debug --no-build
43+
44+
- name: Build WPF .NET Framework 4.7.2 consumer
45+
run: dotnet build consumer-wpf/ConsumerWpf.csproj -c Debug
46+
47+
- name: Record SQL integration limitation
48+
run: Add-Content $env:GITHUB_STEP_SUMMARY "SQL integration is not run in hosted CI because it requires a provisioned SQL Server and restricted test identity. The provider is compiled above."

‎.github/workflows/release.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: GitHub Release
2+
3+
on:
4+
push:
5+
tags: ["v*"]
6+
7+
permissions:
8+
contents: write
9+
10+
jobs:
11+
validate-and-release:
12+
runs-on: windows-latest
13+
steps:
14+
- name: Checkout tagged source
15+
uses: actions/checkout@v4
16+
17+
- name: Set up .NET
18+
uses: actions/setup-dotnet@v4
19+
with:
20+
dotnet-version: 9.0.x
21+
22+
- name: Configure native release build
23+
run: cmake -S . -B build-release -A x64
24+
25+
- name: Build native Core
26+
run: cmake --build build-release --config Release
27+
28+
- name: Run release-safe native tests
29+
run: ctest --test-dir build-release -C Release --output-on-failure -R "^(BasaltDB_tests|BasaltCore_tests|BasaltCore_scheduler_policy_tests|BasaltCore_worker_test|BasaltStorage_contract_tests)$"
30+
31+
- name: Build managed Core and SQL provider
32+
run: |
33+
dotnet build BasaltCore/BasaltCore.csproj -c Release
34+
dotnet build BasaltCore.SqlServer/BasaltCore.SqlServer.csproj -c Release
35+
36+
- name: Build and run modern Embedded consumer
37+
run: |
38+
dotnet build consumer-smoke/Consumer.csproj -c Release
39+
dotnet run --project consumer-smoke/Consumer.csproj -c Release --no-build
40+
41+
- name: Build WPF .NET Framework 4.7.2 consumer
42+
run: dotnet build consumer-wpf/ConsumerWpf.csproj -c Release
43+
44+
- name: Create GitHub Release
45+
uses: softprops/action-gh-release@v2
46+
with:
47+
generate_release_notes: true

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to Basalt are documented here.
4+
5+
This project follows [Semantic Versioning](https://semver.org/): incompatible public or durable-format changes require a major version, backward-compatible features require a minor version, and backward-compatible fixes require a patch version. Prerelease identifiers may be used before a stable release.
6+
7+
## [Unreleased]
8+
9+
### Added
10+
11+
- Storage-neutral managed API for Embedded and SQL Server providers.
12+
- Typed jobs, durable retry and idempotent enqueue.
13+
- Durable schedules, static workflow DAGs, management, recovery, leases, and fencing.
14+
- Simplified managed API, SQL migration modes, and .NET Framework 4.7.2/WPF consumer support.
15+
16+
### Changed
17+
18+
- Managed management models expose enums and .NET-friendly time values.
19+
20+
### Fixed
21+
22+
- Requeue clears the previous terminal ledger entry atomically.
23+
- Embedded execution listing tolerates concurrent retry transitions.

‎CONTRIBUTING.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Contributing to Basalt
2+
3+
Thank you for helping improve Basalt. Please open an issue before a large change, especially one affecting the public API or durable formats.
4+
5+
## Development setup
6+
7+
Basalt's supported development path is Windows x64 with CMake, a C compiler, and the .NET SDK.
8+
9+
```powershell
10+
cmake -S . -B build -A x64
11+
cmake --build build --config Debug
12+
ctest --test-dir build -C Debug --output-on-failure -R "^(BasaltDB_tests|BasaltCore_tests|BasaltCore_scheduler_policy_tests|BasaltCore_worker_test|BasaltStorage_contract_tests)$"
13+
14+
dotnet build BasaltCore/BasaltCore.csproj -c Debug
15+
dotnet build BasaltCore.SqlServer/BasaltCore.SqlServer.csproj -c Debug
16+
dotnet build consumer-smoke/Consumer.csproj -c Debug
17+
dotnet run --project consumer-smoke/Consumer.csproj -c Debug --no-build
18+
dotnet build consumer-wpf/ConsumerWpf.csproj -c Debug
19+
```
20+
21+
SQL integration tests require a separately configured SQL Server instance and are not part of the credential-free default CI job.
22+
23+
## Pull requests
24+
25+
- Keep changes focused and preserve existing durable behavior unless the issue explicitly requires a versioned format change.
26+
- Add or update focused tests for changed behavior.
27+
- Update documentation when public behavior changes.
28+
- Do not commit build outputs, credentials, connection strings, or local databases.
29+
- Describe compatibility and persistence-format impact in the pull request template.
30+
31+
By contributing, you agree that your contribution is licensed under the MIT License.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Vanderhell
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
# Basalt
22

3-
Basalt is a durable background-job, scheduling, and static-workflow engine for .NET. Use the same strongly typed API with a local Embedded store or a shared SQL Server store.
3+
Basalt is a durable background-job, scheduling, and static-workflow engine for .NET with interchangeable Embedded and SQL Server storage.
4+
5+
## Features
6+
7+
- Strongly typed jobs with durable enqueue, retry, and idempotency
8+
- Interval, daily, delayed, one-off, and cron scheduling
9+
- Static workflow DAGs and management APIs
10+
- Crash recovery, leases, fencing, and multiprocess coordination
11+
- Local Embedded storage or a dedicated schema in an existing SQL Server database
12+
- .NET 8 and .NET Framework 4.7.2/WPF consumers
13+
14+
## Embedded in 30 seconds
415

516
```csharp
617
using var basalt = Basalt.Embedded(@"C:\data\jobs");
@@ -14,7 +25,9 @@ await basalt.EnqueueAsync(new SendInvoice(123), key: "invoice:123", retry: 5);
1425
await basalt.StopAsync();
1526
```
1627

17-
SQL Server changes only storage creation; job code stays identical:
28+
## SQL Server
29+
30+
SQL Server changes only storage creation; handler and job code stays identical:
1831

1932
```csharp
2033
using var basalt = Basalt.SqlServer(connectionString, sql =>
@@ -24,16 +37,19 @@ using var basalt = Basalt.SqlServer(connectionString, sql =>
2437
});
2538
```
2639

27-
```csharp
28-
await basalt.EveryAsync("sync", TimeSpan.FromMinutes(5), new SyncJob());
29-
await basalt.Workflow("invoice")
30-
.Add("create", new CreateInvoice())
31-
.Then("send", new SendInvoice(123))
32-
.SubmitAsync();
33-
```
34-
3540
SQL storage does not execute work by itself. Every process intended to execute jobs must register its handlers and call `StartAsync`.
3641

37-
Basalt provides at-least-once execution. Durable enqueue confirms submission, not handler completion; external side effects must be idempotent or fenced.
42+
## Documentation
43+
44+
- [Getting started](docs/getting-started.md)
45+
- [Public API](docs/api.md)
46+
- [Cookbook](docs/cookbook.md)
47+
- [Durability contract](docs/durability.md)
48+
- [SQL Server](docs/sql-server.md)
49+
- [Architecture](docs/architecture.md) and [storage choices](docs/storage.md)
50+
51+
Basalt provides **at-least-once execution**. Durable enqueue confirms submission, not handler completion; external side effects must be idempotent or fenced.
52+
53+
## License
3854

39-
See [docs/api.md](docs/api.md) for the complete public API guide.
55+
Basalt is licensed under the [MIT License](LICENSE), copyright © 2026 Vanderhell.

0 commit comments

Comments
 (0)