libsql-orm 0.1.2

A powerful, async-first ORM for libsql with first-class support for Cloudflare Workers and WebAssembly environments. Features include automatic boolean conversion, upsert operations, built-in logging, migrations, and comprehensive query building.
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# Release Guide

This guide explains how to release new versions of libsql-orm to crates.io.

## Prerequisites

1. **GitHub Secrets**: Ensure you have the following secrets configured in your GitHub repository:
   - `CARGO_REGISTRY_TOKEN`: Your crates.io API token

2. **Crates.io Account**: You need an account on [crates.io](https://crates.io) with API access.

## Release Process

### Option 1: Automated Release (Recommended)

#### Step 1: Prepare the Release

Use the provided script to bump versions:

```bash
# Bump to a new version (e.g., 0.1.1)
./scripts/prepare-release.sh 0.1.1
```

This script will:
- Update version in both `Cargo.toml` files
- Update the dependency version in the main crate
- Verify version consistency
- Run basic build checks

#### Step 2: Commit and Tag

```bash
# Review changes
git diff

# Commit the version bump
git add .
git commit -m "Bump version to 0.1.1"

# Create and push a tag
git tag v0.1.1
git push origin v0.1.1
```

#### Step 3: Automated Release

The GitHub Actions workflow will automatically:
1. Validate the release (formatting, tests, documentation)
2. Publish the macro crate to crates.io
3. Wait for the macro crate to be available
4. Publish the main crate to crates.io
5. Create a GitHub release with changelog

### Option 2: Manual Release

#### Step 1: Trigger Manual Workflow

1. Go to the **Actions** tab in your GitHub repository
2. Select the **Release** workflow
3. Click **Run workflow**
4. Enter the version (e.g., `0.1.1`)
5. Set `dry_run` to `false`
6. Click **Run workflow**

#### Step 2: Monitor the Process

The workflow will:
1. **Validate**: Check formatting, run tests, validate versions
2. **Publish Macro Crate**: Publish `libsql-orm-macros` to crates.io
3. **Publish Main Crate**: Publish `libsql-orm` to crates.io
4. **Create Release**: Generate GitHub release with changelog

### Option 3: Dry Run

To test the release process without actually publishing:

```bash
# Use the script for dry run
./scripts/prepare-release.sh 0.1.1
git add .
git commit -m "Bump version to 0.1.1 (dry run)"
git tag v0.1.1
git push origin v0.1.1
```

Or trigger the manual workflow with `dry_run` set to `true`.

## Version Management

### Version Format

Use semantic versioning: `MAJOR.MINOR.PATCH`

- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Version Consistency

Both crates (`libsql-orm` and `libsql-orm-macros`) must have the same version. The release workflow will verify this.

## Release Notes

The automated release will generate release notes from git commits. To write custom release notes:

1. Create a draft release in GitHub
2. Write your release notes
3. Publish the release manually

## Troubleshooting

### Common Issues

1. **Version Mismatch**: Ensure both crates have the same version
2. **Build Failures**: Fix any compilation errors before releasing
3. **Test Failures**: All tests must pass before release
4. **Documentation Errors**: Documentation must build successfully

### Manual Recovery

If the automated release fails:

1. Check the workflow logs for errors
2. Fix the issues
3. Re-run the workflow or create a new tag

### Rollback

To rollback a release:

1. **Crates.io**: Contact crates.io support (releases cannot be deleted)
2. **GitHub**: Delete the release and tag
3. **Code**: Revert the version bump commit

## Security

- Never commit the `CARGO_REGISTRY_TOKEN` to the repository
- Use GitHub secrets for sensitive information
- Review all changes before releasing

## Support

If you encounter issues with the release process:

1. Check the [GitHub Actions documentation](https://docs.github.com/en/actions)
2. Review the workflow logs for detailed error messages
3. Open an issue in the repository

---

**Note**: This release process is designed for the libsql-orm project structure with both a main crate and a macro crate. Adjust the process if your project structure changes.