okc 0.1.0

A local-first tool for AI agents to browse, parse, search, and reason over Open Knowledge Format (OKF) repositories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

---
type: guide
title: Release Process
description: How to create a new OKC release
tags:
  - release
  - operations
  - ci
owner: felix
status: stable
---

# Release Process

## Overview

Releases are automated via [GitHub Actions](https://github.com/guifelix/Open-Knowledge-Catalog/actions). Pushing a
semantic version tag triggers CI validation, binary builds, GitHub Release creation, and crates.io publishing.

## Creating a Release

### 1. Prepare

```bash
# Ensure you're on main and up to date
git checkout main
git pull origin main

# Review what's changed since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo 'HEAD~100')..HEAD

# Update version in Cargo.toml if needed (already at target version)
```

### 2. Generate CHANGELOG

Changelogs are auto-generated from [conventional commits](https://www.conventionalcommits.org/)
using [`git-cliff`](https://git-cliff.org):

```bash
# Dry-run to preview
git cliff --unreleased --strip header

# Generate/update CHANGELOG.md
git cliff --tag v0.1.0 -o CHANGELOG.md
```

Review and commit the result:

```bash
git add CHANGELOG.md
git commit -m "chore: prepare v0.1.0 release"
```

### 3. Tag and Push

```bash
git tag v0.1.0
git push origin v0.1.0
```

### 4. CI Does the Rest

The [release workflow](../.github/workflows/release.yml) will:

1. Run CI checks (fmt, clippy, test)
2. Build release binaries for:
   - `x86_64-unknown-linux-gnu` (Linux glibc)
   - `x86_64-unknown-linux-musl` (Linux musl — fully static)
   - `x86_64-apple-darwin` (Intel macOS)
   - `aarch64-apple-darwin` (Apple Silicon macOS)
   - `x86_64-pc-windows-msvc` (Windows)
3. Create a [GitHub Release](https://github.com/guifelix/Open-Knowledge-Catalog/releases) with binaries and checksums
4. Publish to [crates.io](https://crates.io/crates/okc)

### 5. Verify

```bash
# crates.io
cargo install okc
okc --version

# GitHub Release — download the binary for your platform
# e.g. for linux amd64:
curl -LO https://github.com/guifelix/Open-Knowledge-Catalog/releases/download/v0.1.0/okc-x86_64-unknown-linux-gnu
chmod +x okc-x86_64-unknown-linux-gnu
./okc-x86_64-unknown-linux-gnu --version
```

## Commit Convention

This project uses [Conventional Commits](https://www.conventionalcommits.org/) so `git-cliff` can
auto-generate changelogs. Prefix your commits accordingly:

| Prefix       | Changelog section |
|--------------|-------------------|
| `feat:`      | Added             |
| `fix:`       | Fixed             |
| `perf:`      | Performance       |
| `refactor:`  | Changed           |
| `docs:`      | Documentation     |
| `test:`      | Testing           |
| `chore:`     | Skipped           |
| `ci:`        | Skipped           |

Breaking changes should include `!` after the prefix: `feat!: ...` or a
`BREAKING CHANGE:` footer.

## Prerequisites

| Item | Status |
|------|--------|
| `CRATES_IO_TOKEN` GitHub secret | Set in repo settings |
| CI green on main | Verified automatically |
| CHANGELOG up-to-date | `git cliff --tag x.y.z -o CHANGELOG.md` before tagging |

## One-Time Setup

### crates.io Token

```bash
# Generate a token at https://crates.io/settings/tokens
# Then add it as a repository secret:
gh secret set CRATES_IO_TOKEN
```

Or go to GitHub → Settings → Secrets and variables → Actions → New repository secret.