Crates.io Publishing Analysis: Rust Projects

Executive Summary

Both projects are production-ready but require metadata additions for Crates.io publishing. The projects have:

  • ✅ Clean Cargo.toml structure
  • ✅ Proper licensing (MIT)
  • ✅ Version definitions in place
  • ✅ Comprehensive CI/CD workflows
  • ❌ Missing categories, keywords, and homepages for Crates.io discoverability
  • ❌ No automated Crates.io publishing workflows

PROJECT 1: z-kitty-launcher

Current Cargo.toml Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13

[package]
name = "kitty-launcher"
version = "0.5.1"
edition = "2021"
authors = ["OpenCode Contributors"]
description = "A robust Rust wrapper for kitty terminal emulator with flexible session presets"
license = "MIT"
documentation = "https://github.com/pilakkat1964/kitty-launcher"
repository = "https://github.com/pilakkat1964/kitty-launcher"
readme = "README.md"

[dependencies]
# (No external dependencies - pure Rust)

Metadata Completeness Assessment

Field Status Value Crates.io Required?
name ✅ kitty-launcher YES
version ✅ 0.5.1 YES
edition ✅ 2021 YES
license ✅ MIT YES (recommended)
authors ✅ Present NO (optional)
description ✅ Present (concise) YES
documentation ✅ GitHub pages YES (optional)
repository ✅ GitHub URL YES (recommended)
readme ✅ README.md YES (recommended)
homepage ❌ Missing NO (optional)
keywords ❌ Missing NO (recommended)
categories ❌ Missing NO (recommended)
license-file ⚠️ Implicit (LICENSE file) NO (auto-detected)
exclude ⚠️ Missing NO (optional)

Version Definition Method

  • Source: Hardcoded in src/main.rs (line 33)
  • Constant: const VERSION: &str = "0.5.1";
  • Sync Status: ⚠️ Manual synchronization required with Cargo.toml (0.5.1)
  • Issue: Version duplication - maintained in two places
  • Recommendation: Use env!("CARGO_PKG_VERSION") macro instead

Current GitHub Actions Workflows

CI Workflow (.github/workflows/build-and-test.yml)

  • ✅ Runs on push/PR
  • ✅ Tests on stable Rust
  • ✅ Cargo audit security scanning
  • ✅ Code formatting checks
  • ✅ Clippy linting
  • ✅ Multi-architecture builds (AMD64, ARM64)
  • ❌ No Crates.io publish job

Release Workflow (.github/workflows/release.yml)

  • ✅ Triggered on tag push (v*)
  • ✅ Builds multi-architecture binaries
  • ✅ Generates Debian packages
  • ✅ Creates GitHub release
  • ❌ No Crates.io publishing step

Issues & Inconsistencies Found

  1. Version Duplication: VERSION constant in src/main.rs must be kept in sync with Cargo.toml
  2. Missing Crates.io Metadata:
    • No keywords for discoverability
    • No categories classification
    • No homepage field (though not required)
  3. Release Workflow Gap: No automated publishing to Crates.io
  4. Documentation URL: Points to GitHub repo instead of docs.rs (Crates.io automatic documentation)

What’s Missing for Automated Crates.io Publishing

  • Keywords metadata (3-5 terms): ["terminal", "kitty", "session-manager", "launcher"]
  • Categories metadata (1-5): ["command-line-utilities", "development-tools"]
  • Homepage field (optional): Could be docs site
  • Crates.io token in GitHub secrets
  • Publishing step in release.yml workflow
  • Crates.io publishing documentation
  • Cargo.toml validation in CI

Suggested Cargo.toml Improvements

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

[package]
name = "kitty-launcher"
version = "0.5.1"
edition = "2021"
authors = ["OpenCode Contributors"]
description = "A robust Rust wrapper for kitty terminal emulator with flexible session presets"
license = "MIT"
license-file = "LICENSE"  # Explicit LICENSE path (optional but recommended)
documentation = "https://docs.rs/kitty-launcher"  # Will auto-update on Crates.io
repository = "https://github.com/pilakkat1964/kitty-launcher"
homepage = "https://github.com/pilakkat1964/kitty-launcher"  # Project home
readme = "README.md"
keywords = ["terminal", "kitty", "session-manager", "launcher"]  # NEW
categories = ["command-line-utilities", "development-tools"]  # NEW
exclude = [
    ".github",
    "docs",
    "debian",
    "scripts",
    "*.1",
    "*.info"
]  # NEW - Reduce package size

[dependencies]

[profile.release]
opt-level = 3
lto = true
strip = true  # NEW - Automatic binary stripping

Phase 1: Prepare

  1. Add keywords and categories to Cargo.toml
  2. Verify documentation builds correctly: cargo doc --open
  3. Test packaging: cargo package --allow-dirty
  4. Add LICENSE file explicitly to Cargo.toml

Phase 2: Register Token

  1. Create Crates.io account at https://crates.io
  2. Generate API token from account settings
  3. Add token to GitHub secrets: CARGO_REGISTRY_TOKEN

Phase 3: Automate Release

  1. Add Crates.io publishing step to release.yml
  2. Test with pre-release tag (e.g., v0.5.2-alpha)
  3. Verify package appears on Crates.io

Phase 4: Documentation

  1. Create PUBLISHING.md guide
  2. Document version sync strategy
  3. Update CONTRIBUTING.md with release procedures

PROJECT 2: z-rclone-mount-applete

Current Cargo.toml Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

[package]
name = "rclone-mount-tray"
version = "0.1.0"
edition = "2021"
authors = ["RClone Tray Contributors"]
description = "System tray applet for on-demand rclone mount management"
license = "MIT"

[dependencies]
tokio = { version = "1.37", features = ["rt-multi-thread", "macros", "process"] }
serde = { version = "1.0", features = ["derive"] }
toml = "0.8"
tracing = "0.1"
tracing-subscriber = "0.3"
anyhow = "1.0"
dirs = "5.0"

[profile.release]
opt-level = 3
lto = true

Metadata Completeness Assessment

Field Status Value Crates.io Required?
name ✅ rclone-mount-tray YES
version ✅ 0.1.0 YES
edition ✅ 2021 YES
license ✅ MIT YES (recommended)
authors ✅ Present NO (optional)
description ✅ Present (concise) YES
documentation ❌ Missing YES (recommended)
repository ❌ Missing YES (recommended)
readme ❌ Missing NO (auto-detected)
homepage ❌ Missing NO (optional)
keywords ❌ Missing NO (recommended)
categories ❌ Missing NO (recommended)
license-file ⚠️ Implicit NO (auto-detected)
exclude ⚠️ Missing NO (optional)

Version Definition Method

  • Source: Only in Cargo.toml
  • Constant: Version 0.1.0
  • Sync Status: ✅ Single source of truth
  • Access Method: Via env!("CARGO_PKG_VERSION") macro (not currently used)
  • Advantage: No duplication issues

Current GitHub Actions Workflows

CI Workflow (.github/workflows/ci.yml)

  • ✅ Runs on push/PR to main and develop
  • ✅ Tests on stable, beta, nightly Rust
  • ✅ Cargo audit security scanning
  • ✅ Code formatting and clippy linting
  • ✅ Release build job
  • ✅ Multi-version testing
  • ❌ No Crates.io publish job

Release Workflow (.github/workflows/release.yml)

  • ✅ Triggered on tag push (v*)
  • ✅ Builds release binary with optimizations
  • ✅ Creates GitHub release with assets
  • ✅ Generates checksums
  • ✅ Creates source tarball
  • ⚠️ Simplified compared to kitty-launcher (no multi-arch)
  • ❌ No Crates.io publishing step

Issues & Inconsistencies Found

  1. Critical Missing Fields:
    • No repository field (required for Crates.io best practices)
    • No documentation field (will default to docs.rs)
    • No readme field (won’t fail but prevents custom README)
  2. Release Workflow Issues:
    • No multi-architecture build (only native AMD64)
    • No ARM64 cross-compilation support
    • Less comprehensive than kitty-launcher
  3. Package Metadata Gap:
    • No keywords for discoverability
    • No categories classification
    • No homepage documentation
  4. Dependency Tracking:
    • 6 external crates (well-chosen but needs monitoring)
    • Good security practices (audit in CI) but unpublished

What’s Missing for Automated Crates.io Publishing

  • Repository field in Cargo.toml
  • Documentation field in Cargo.toml
  • Keywords metadata: ["rclone", "tray", "system-tray", "mount-manager"]
  • Categories metadata: ["command-line-utilities", "gui"]
  • Readme field pointing to README.md
  • Crates.io token in GitHub secrets
  • Publishing step in release.yml workflow
  • Multi-architecture build support in release workflow
  • Crates.io publishing documentation

Suggested Cargo.toml Improvements

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

[package]
name = "rclone-mount-tray"
version = "0.1.0"
edition = "2021"
authors = ["RClone Tray Contributors"]
description = "System tray applet for on-demand rclone mount management"
license = "MIT"
license-file = "LICENSE"  # NEW - Explicit LICENSE path
documentation = "https://docs.rs/rclone-mount-tray"  # NEW
repository = "https://github.com/pilakkat1964/z-rclone-mount-applete"  # NEW
homepage = "https://github.com/pilakkat1964/z-rclone-mount-applete"  # NEW
readme = "README.md"  # NEW
keywords = ["rclone", "tray", "system-tray", "mount-manager"]  # NEW
categories = ["command-line-utilities", "gui"]  # NEW
exclude = [
    ".github",
    "docs",
    "debian",
    "scripts",
    "data",
    "rclone-config-manager"
]  # NEW - Reduce package size

[dependencies]
tokio = { version = "1.37", features = ["rt-multi-thread", "macros", "process"] }
serde = { version = "1.0", features = ["derive"] }
toml = "0.8"
tracing = "0.1"
tracing-subscriber = "0.3"
anyhow = "1.0"
dirs = "5.0"

[profile.release]
opt-level = 3
lto = true
strip = true  # NEW - Automatic binary stripping

Phase 1: Prepare

  1. Add missing repository and documentation fields to Cargo.toml
  2. Add keywords, categories, and readme fields
  3. Verify documentation builds correctly: cargo doc --open
  4. Test packaging: cargo package --allow-dirty
  5. Create proper LICENSE file reference

Phase 2: Align Release Process

  1. Add multi-architecture build support (like kitty-launcher)
  2. Add ARM64 cross-compilation for consistency
  3. Generate Debian packages for both architectures
  4. Create comprehensive release notes

Phase 3: Register Token

  1. Create Crates.io account at https://crates.io
  2. Generate API token from account settings
  3. Add token to GitHub secrets: CARGO_REGISTRY_TOKEN

Phase 4: Automate Release

  1. Add Crates.io publishing step to release.yml
  2. Test with pre-release tag (e.g., v0.1.1-alpha)
  3. Verify package appears on Crates.io

Phase 5: Documentation

  1. Create PUBLISHING.md guide
  2. Document multi-architecture build process
  3. Update CONTRIBUTING.md with release procedures
  4. Add packaging instructions to docs/

Comparison Matrix

Aspect kitty-launcher rclone-mount-applete
Current Version 0.5.1 0.1.0
Version in Code Yes (hardcoded) No (Cargo.toml only)
Dependencies 0 external 6 external
Binary Size ~509 KB ~975 KB
CI Jobs 3 (build, test, audit) 5 (test, fmt, clippy, audit, build)
Release Builds Multi-arch (AMD64, ARM64) Single arch (AMD64)
Crates.io Ready 70% 50%

Crates.io Readiness Scores

kitty-launcher: 70/100 ✅

  • ✅ Complete core metadata
  • ✅ Good description and keywords
  • ✅ Clean dependency tree
  • ❌ Missing keywords/categories
  • ❌ Version duplication
  • ❌ No publish workflow

rclone-mount-applete: 50/100 ⚠️

  • ✅ Complete dependency list
  • ✅ Good test coverage
  • ❌ Missing repository field
  • ❌ Missing documentation field
  • ❌ Missing keywords/categories
  • ❌ No publish workflow
  • ❌ Limited multi-arch support

Unified Implementation Plan

Timeline: 2-3 weeks

Week 1: Prepare Both Projects

  • Day 1-2: Update Cargo.toml with missing fields
  • Day 3-4: Add keywords and categories
  • Day 5: Test local packaging (cargo package --allow-dirty)

Week 2: Automate Publishing

  • Day 1-2: Set up Crates.io accounts and tokens
  • Day 3-4: Add publishing steps to GitHub Actions
  • Day 5: Test with alpha releases

Week 3: Documentation & Training

  • Day 1-2: Create PUBLISHING.md guides
  • Day 3-4: Update CONTRIBUTING.md files
  • Day 5: Final testing and validation

Suggested Keywords & Categories

kitty-launcher

1
2

keywords = ["terminal", "kitty", "session-manager", "launcher", "tui"]
categories = ["command-line-utilities", "development-tools::build-utils"]

rclone-mount-applete

1
2

keywords = ["rclone", "tray", "system-tray", "mount-manager", "applet"]
categories = ["command-line-utilities", "gui"]

Next Steps (Priority Order)

  1. Immediate (This week):
    • Add keywords and categories to both Cargo.toml files
    • Add missing fields (repository, documentation, readme, homepage)
    • Update documentation URL to use docs.rs
  2. Short-term (Next 2 weeks):
    • Create Crates.io accounts
    • Set up GitHub secrets with API tokens
    • Add publishing steps to release workflows
  3. Medium-term (Monthly):
    • Enhance multi-architecture support for both projects
    • Add pre-release testing procedures
    • Create unified publishing documentation
  4. Long-term (Quarterly):
    • Monitor Crates.io downloads and feedback
    • Update dependencies regularly
    • Maintain version sync strategies

Key Recommendations

For Both Projects

  1. Use env!("CARGO_PKG_VERSION") to eliminate version duplication
  2. Add standard exclude patterns to reduce package size
  3. Enable binary stripping in release profile
  4. Document version sync strategy for future maintainers
  5. Set up version bump automation (consider cargo-release crate)

For kitty-launcher

  1. Fix version duplication (hardcoded vs Cargo.toml)
  2. Add keywords: ["terminal", "kitty", "session-manager", "launcher"]
  3. Add categories: ["command-line-utilities", "development-tools::build-utils"]

For rclone-mount-applete

  1. Add repository field (critical)
  2. Add documentation field (critical)
  3. Add keywords: ["rclone", "tray", "system-tray", "mount-manager"]
  4. Add categories: ["command-line-utilities", "gui"]
  5. Enhance multi-architecture build support in release workflow
  6. Add ARM64 cross-compilation (like kitty-launcher)

Crates.io Publishing Workflow Template

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

# Add to .github/workflows/release.yml

publish_crates_io:
  name: Publish to Crates.io
  needs: [build-matrix]  # or build job
  runs-on: ubuntu-latest
  if: startsWith(github.ref, 'refs/tags/v')
  steps:
    - uses: actions/checkout@v4
    
    - uses: dtolnay/rust-toolchain@stable
    
    - name: Publish to Crates.io
      run: cargo publish --token $
      env:
        CARGO_REGISTRY_TOKEN: $
    
    - name: Wait for publish
      run: sleep 10  # Crates.io indexing delay
    
    - name: Verify publication
      run: |
        PACKAGE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
        VERSION=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
        echo "Verifying $PACKAGE_NAME v$VERSION on Crates.io..."
        curl -s https://crates.io/api/v1/crates/$PACKAGE_NAME/$VERSION | grep -q '"version"' && echo "✅ Published successfully!" || echo "⚠️ Not yet indexed"

Analysis Date: April 16, 2026
Status: Ready for implementation
Estimated Effort: 2-3 weeks for full implementation

Updated: