docs: add comprehensive publication guide for v1.0.0
- Step-by-step crates.io setup and publication - Step-by-step PyPI setup and publication - GitHub Actions automation template - Post-publication checklist - Marketing & announcement strategy - Success metrics and tracking - Known issues and limitations Guide includes all commands needed to complete publication after credentials are configured.
This commit is contained in:
Melvin Alvarez
@@ -0,0 +1,395 @@
|
||||
# OptimizR v1.0.0 Publication Guide
|
||||
|
||||
**Status:** ✅ READY FOR PUBLICATION
|
||||
**Date:** February 16, 2026
|
||||
**Repository:** https://github.com/ThotDjehuty/optimiz-r
|
||||
**Tag:** v1.0.0
|
||||
|
||||
---
|
||||
|
||||
## ✅ Completed Preparation
|
||||
|
||||
### 1. Fixed Cargo.toml (Commit: f44280e)
|
||||
- ✅ Removed `python-bindings` from default features
|
||||
- ✅ Updated version: 0.3.0 → 1.0.0
|
||||
- ✅ Updated authors: HFThot Research Lab <contact@hfthot-lab.eu>
|
||||
- ✅ Updated repository URL: https://github.com/ThotDjehuty/optimiz-r
|
||||
|
||||
### 2. Fixed pyproject.toml (Commit: f44280e, a3117fe)
|
||||
- ✅ Updated version: 0.3.0 → 1.0.0
|
||||
- ✅ Updated authors: HFThot Research Lab
|
||||
- ✅ Updated URLs (homepage, docs, repository)
|
||||
- ✅ Fixed maturin configuration to use python-bindings feature
|
||||
|
||||
### 3. Updated README.md (Commit: f44280e)
|
||||
- ✅ Version badge: 0.3.0 → 1.0.0
|
||||
- ✅ What's New section updated for v1.0.0
|
||||
- ✅ Citation author updated
|
||||
- ✅ Contact information updated
|
||||
|
||||
### 4. Added .gitignore (Commit: 0dfb9b8)
|
||||
- ✅ Excluded wheels/ directory from git
|
||||
|
||||
### 5. Created RELEASE_NOTES_v1.0.0.md (Commit: 07d4529)
|
||||
- ✅ Comprehensive release notes
|
||||
- ✅ Breaking changes documentation
|
||||
- ✅ Migration guide
|
||||
- ✅ Roadmap for future versions
|
||||
|
||||
### 6. Build Verification
|
||||
- ✅ `cargo publish --dry-run` - SUCCESS
|
||||
- ✅ `maturin build --release --features python-bindings` - SUCCESS
|
||||
- ✅ Wheel built: `optimizr-1.0.0-cp38-abi3-macosx_10_12_x86_64.whl`
|
||||
|
||||
### 7. Git Tag & Push
|
||||
- ✅ Created tag: v1.0.0
|
||||
- ✅ Pushed to GitHub: main branch + v1.0.0 tag
|
||||
|
||||
---
|
||||
|
||||
## 📋 Next Steps: Actual Publication
|
||||
|
||||
### Step 1: Set Up crates.io Account
|
||||
|
||||
1. **Create Account** (if not already done)
|
||||
- Visit: https://crates.io/
|
||||
- Sign in with GitHub account
|
||||
|
||||
2. **Generate API Token**
|
||||
- Go to: https://crates.io/settings/tokens
|
||||
- Create new token: "OptimizR v1.0.0 Publication"
|
||||
- Copy the token (you won't see it again)
|
||||
|
||||
3. **Configure Credentials**
|
||||
```bash
|
||||
cargo login <your-crates-io-token>
|
||||
```
|
||||
This creates `~/.cargo/credentials` with your token
|
||||
|
||||
### Step 2: Publish to crates.io
|
||||
|
||||
```bash
|
||||
cd /Users/melvinalvarez/Documents/Workspace/optimiz-r
|
||||
|
||||
# Final verification (already tested ✅)
|
||||
cargo publish --dry-run
|
||||
|
||||
# Actual publication
|
||||
cargo publish
|
||||
|
||||
# Expected output:
|
||||
# Updating crates.io index
|
||||
# Packaging optimizr v1.0.0 (/Users/.../optimiz-r)
|
||||
# Uploading optimizr v1.0.0
|
||||
# Published optimizr v1.0.0
|
||||
```
|
||||
|
||||
**Verification:**
|
||||
- Visit: https://crates.io/crates/optimizr
|
||||
- Should show v1.0.0 within a few minutes
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Set Up PyPI Account
|
||||
|
||||
1. **Create PyPI Account** (if not already done)
|
||||
- Visit: https://pypi.org/account/register/
|
||||
- Verify email
|
||||
|
||||
2. **Enable 2FA** (required for publishing)
|
||||
- Settings → Account Security
|
||||
- Set up 2FA with authenticator app
|
||||
|
||||
3. **Create API Token**
|
||||
- Account settings → API tokens
|
||||
- Scope: Entire account (or specific project after first upload)
|
||||
- Copy the token (starts with `pypi-`)
|
||||
|
||||
4. **Configure Credentials**
|
||||
```bash
|
||||
# Create ~/.pypirc
|
||||
cat > ~/.pypirc << 'EOF'
|
||||
[distutils]
|
||||
index-servers =
|
||||
pypi
|
||||
|
||||
[pypi]
|
||||
username = __token__
|
||||
password = pypi-YOUR_TOKEN_HERE
|
||||
EOF
|
||||
|
||||
# Secure the file
|
||||
chmod 600 ~/.pypirc
|
||||
```
|
||||
|
||||
### Step 4: Publish to PyPI
|
||||
|
||||
```bash
|
||||
cd /Users/melvinalvarez/Documents/Workspace/optimiz-r
|
||||
|
||||
# Build wheels for multiple platforms (current: macOS only)
|
||||
# Option 1: Build for current platform only
|
||||
maturin build --release --features python-bindings
|
||||
|
||||
# Option 2: Use maturin publish which builds and uploads
|
||||
maturin publish --username __token__ --password pypi-YOUR_TOKEN_HERE
|
||||
|
||||
# OR if ~/.pypirc is configured:
|
||||
maturin publish
|
||||
```
|
||||
|
||||
**Multi-Platform Wheels (Optional but Recommended):**
|
||||
|
||||
To publish wheels for Linux, Windows, and macOS:
|
||||
|
||||
```bash
|
||||
# Use GitHub Actions (recommended)
|
||||
# Already have .github/workflows/ci.yml - extend it with:
|
||||
# - maturin publish on tag push
|
||||
# - Build wheels for: Linux (x86_64, aarch64), Windows (x86_64), macOS (x86_64, aarch64)
|
||||
|
||||
# Manual alternative: Use cibuildwheel
|
||||
pip install cibuildwheel
|
||||
cibuildwheel --platform linux
|
||||
cibuildwheel --platform windows
|
||||
cibuildwheel --platform macos
|
||||
|
||||
# Upload all wheels
|
||||
maturin upload target/wheels/*
|
||||
```
|
||||
|
||||
**Verification:**
|
||||
- Visit: https://pypi.org/project/optimizr/
|
||||
- Should show v1.0.0 within a few minutes
|
||||
- Test installation:
|
||||
```bash
|
||||
pip install optimizr==1.0.0
|
||||
python -c "import optimizr; print(optimizr.__version__)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 GitHub Actions Automation (Recommended)
|
||||
|
||||
To automate future releases, update `.github/workflows/ci.yml`:
|
||||
|
||||
```yaml
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
publish-crates:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions-rs/toolchain@v1
|
||||
with:
|
||||
toolchain: stable
|
||||
- name: Publish to crates.io
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_TOKEN }}
|
||||
run: cargo publish --token $CARGO_REGISTRY_TOKEN
|
||||
|
||||
publish-pypi:
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-latest, macos-latest, windows-latest]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.11'
|
||||
- name: Install maturin
|
||||
run: pip install maturin
|
||||
- name: Build wheels
|
||||
run: maturin build --release --features python-bindings
|
||||
- name: Publish to PyPI
|
||||
env:
|
||||
MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
|
||||
run: maturin publish --username __token__ --password $MATURIN_PYPI_TOKEN
|
||||
```
|
||||
|
||||
**Setup Secrets:**
|
||||
1. GitHub repo → Settings → Secrets and variables → Actions
|
||||
2. Add secrets:
|
||||
- `CRATES_TOKEN`: Your crates.io API token
|
||||
- `PYPI_TOKEN`: Your PyPI API token (starts with `pypi-`)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Post-Publication Checklist
|
||||
|
||||
### Immediate (After Publishing)
|
||||
|
||||
- [ ] **Verify crates.io**: https://crates.io/crates/optimizr/1.0.0
|
||||
- [ ] **Verify PyPI**: https://pypi.org/project/optimizr/1.0.0
|
||||
- [ ] **Test Rust installation**:
|
||||
```bash
|
||||
cargo new test-optimizr
|
||||
cd test-optimizr
|
||||
cargo add optimizr
|
||||
cargo build
|
||||
```
|
||||
- [ ] **Test Python installation**:
|
||||
```bash
|
||||
python -m venv test-env
|
||||
source test-env/bin/activate
|
||||
pip install optimizr==1.0.0
|
||||
python -c "import optimizr; print(optimizr.__version__)"
|
||||
```
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
- [ ] **Update OPEN_SOURCE_STRATEGY.md**:
|
||||
```markdown
|
||||
#### 2. **Optimiz-R** - Portfolio Optimization Engine
|
||||
- **Current Status:** ✅ v1.0.0 published (crates.io + PyPI)
|
||||
- **Repository:** https://github.com/ThotDjehuty/optimiz-r
|
||||
- **Documentation:** https://optimiz-r.readthedocs.io
|
||||
- **Installation:** `cargo add optimizr` or `pip install optimizr`
|
||||
```
|
||||
|
||||
- [ ] **Create GitHub Release**:
|
||||
- Go to: https://github.com/ThotDjehuty/optimiz-r/releases/new
|
||||
- Tag: v1.0.0
|
||||
- Title: "OptimizR v1.0.0 - First Stable Release"
|
||||
- Description: Copy from RELEASE_NOTES_v1.0.0.md
|
||||
- Attach assets: wheels from target/wheels/
|
||||
|
||||
### Marketing & Announcements
|
||||
|
||||
- [ ] **Blog Post** (https://hfthot-lab.eu):
|
||||
```markdown
|
||||
Title: "OptimizR v1.0.0: High-Performance Optimization in Rust"
|
||||
|
||||
Sections:
|
||||
1. What is OptimizR?
|
||||
2. Performance benchmarks (50-100× speedup)
|
||||
3. Key features & algorithms
|
||||
4. Getting started (Rust & Python)
|
||||
5. Why open source?
|
||||
6. Roadmap & community
|
||||
```
|
||||
|
||||
- [ ] **Social Media Announcements**:
|
||||
- Twitter/X: "🚀 OptimizR v1.0.0 is live! High-performance optimization algorithms in Rust with Python bindings. 50-100× faster than pure Python. MIT licensed. #rustlang #python #optimization"
|
||||
- LinkedIn: Professional announcement with benchmarks
|
||||
- Reddit:
|
||||
- r/rust: "OptimizR v1.0.0: Optimization algorithms with 50-100× speedup"
|
||||
- r/Python: "Fast optimization library (Rust-powered) now on PyPI"
|
||||
- r/algotrading: "Open-source optimization for quant finance"
|
||||
|
||||
- [ ] **Hacker News** (https://news.ycombinator.com/submit):
|
||||
```
|
||||
Title: "OptimizR v1.0.0 – High-Performance Optimization Algorithms in Rust"
|
||||
URL: https://github.com/ThotDjehuty/optimiz-r
|
||||
```
|
||||
|
||||
- [ ] **Dev.to Article**:
|
||||
- "Building a 100× Faster Optimization Library with Rust and PyO3"
|
||||
- Include benchmarks, code examples, lessons learned
|
||||
|
||||
### Community Building
|
||||
|
||||
- [ ] **Update README badges**:
|
||||
- Add crates.io badge: `[](https://crates.io/crates/optimizr)`
|
||||
- Add PyPI badge: `[](https://pypi.org/project/optimizr/)`
|
||||
- Add downloads badge
|
||||
|
||||
- [ ] **Create Discord/Discussions**:
|
||||
- Enable GitHub Discussions for Q&A
|
||||
- Or create Discord server for community
|
||||
|
||||
- [ ] **Contributing Guide** (CONTRIBUTING.md):
|
||||
- How to contribute
|
||||
- Development setup
|
||||
- Code style guidelines
|
||||
- PR process
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Metrics (Month 1)
|
||||
|
||||
### Downloads
|
||||
- **Target crates.io**: 100 downloads
|
||||
- **Target PyPI**: 500 downloads
|
||||
|
||||
### Community
|
||||
- **GitHub Stars**: 50+
|
||||
- **Issues/Questions**: 5-10
|
||||
- **Contributors**: 2-3
|
||||
|
||||
### Documentation
|
||||
- **ReadTheDocs views**: 1000+
|
||||
- **Tutorial completions**: 50+
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Known Issues & Limitations
|
||||
|
||||
### Current Limitations
|
||||
1. **Single-platform wheels**: Only macOS built locally
|
||||
- **Solution**: Use GitHub Actions for multi-platform builds
|
||||
|
||||
2. **Compiler warnings**: 8 unused variable warnings
|
||||
- **Solution**: Run `cargo fix --lib -p optimizr` and commit
|
||||
|
||||
3. **Documentation**: Some examples could be more comprehensive
|
||||
- **Solution**: Add more real-world use cases to tutorials
|
||||
|
||||
### Not Yet Implemented
|
||||
- GPU acceleration (roadmap: v1.2.0)
|
||||
- Additional DE variants (JADE, SHADE) - roadmap: v1.1.0
|
||||
- Multi-objective optimization - roadmap: v2.0.0
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
If publication issues occur:
|
||||
|
||||
**Crates.io Issues:**
|
||||
- Check: https://crates.io/policies
|
||||
- Email: help@crates.io
|
||||
- Docs: https://doc.rust-lang.org/cargo/reference/publishing.html
|
||||
|
||||
**PyPI Issues:**
|
||||
- Check: https://pypi.org/help/
|
||||
- Docs: https://packaging.python.org/tutorials/packaging-projects/
|
||||
- Forum: https://discuss.python.org/c/packaging/14
|
||||
|
||||
**General:**
|
||||
- Email: contact@hfthot-lab.eu
|
||||
- GitHub Issues: https://github.com/ThotDjehuty/optimiz-r/issues
|
||||
|
||||
---
|
||||
|
||||
## ✅ Summary
|
||||
|
||||
**OptimizR v1.0.0 is READY FOR PUBLICATION**
|
||||
|
||||
All code changes committed ✅
|
||||
All tests passing ✅
|
||||
Documentation complete ✅
|
||||
Git tag created (v1.0.0) ✅
|
||||
Release notes written ✅
|
||||
Pushed to GitHub ✅
|
||||
|
||||
**Next Action:** Set up crates.io and PyPI credentials, then run:
|
||||
```bash
|
||||
cargo publish # For Rust users
|
||||
maturin publish # For Python users
|
||||
```
|
||||
|
||||
**Total Time Invested:** ~2 hours (as estimated)
|
||||
|
||||
**Publication Time:** 15-30 minutes (once credentials configured)
|
||||
|
||||
---
|
||||
|
||||
**Ready to publish! 🚀**
|
||||
Reference in New Issue
Block a user