docs/plugin-publishing.md
This guide shows how to publish and distribute your plugins, whether they are backend plugins or tool plugins. Publishing makes your plugins available to other users and ensures they can be easily installed and maintained.
Before publishing your plugin, ensure you have:
metadata.lua - Plugin metadata with name, version, description, and authorREADME.md - Basic usage instructions and examplestest/ directory - Test scripts for verificationThe easiest way to start is with the mise-tool-plugin-template:
# Clone the template
git clone https://github.com/jdx/mise-tool-plugin-template my-plugin
cd my-plugin
# Remove template history and set up your own repository
rm -rf .git
git init
git remote add origin https://github.com/username/my-plugin.git
# Customize for your plugin
# Edit metadata.lua, hooks/*.lua, README.md, etc.
Alternatively, create a repository from scratch:
# Create plugin directory
mkdir my-plugin
cd my-plugin
# Initialize git repository
git init
git remote add origin https://github.com/username/my-plugin.git
# Create initial structure
touch metadata.lua
mkdir -p test
echo "# My Plugin" > README.md
Organize your plugin with this structure:
my-plugin/
├── metadata.lua # Plugin metadata
├── README.md # Basic documentation
├── test/ # Test scripts
│ └── test.sh
├── .gitignore # Git ignore rules
└── [implementation files]
For backend plugins:
backend-plugin/
├── metadata.lua # Backend methods implementation
├── README.md
└── test/
└── test.sh
For tool plugins:
tool-plugin/
├── metadata.lua # Plugin metadata
├── hooks/ # Hook implementations
│ ├── available.lua
│ ├── pre_install.lua
│ └── env_keys.lua
├── lib/ # Helper libraries
│ └── helper.lua
├── README.md
└── test/
└── test.sh
Create a .gitignore file:
# Temporary files
*.tmp
*.temp
.DS_Store
Thumbs.db
# Test artifacts
test/tmp/
test/output/
# IDE files
.vscode/
.idea/
*.swp
*.swo
# OS files
*.log
Use semantic versioning (SemVer) for your plugin releases:
Update version in metadata.lua:
PLUGIN = {
name = "my-plugin",
version = "1.2.3", -- Update this for each release
description = "My awesome plugin",
author = "Your Name"
}
Create git tags for releases:
# Tag the current commit
git tag -a v1.2.3 -m "Release version 1.2.3"
# Push tags to repository
git push origin --tags
Create comprehensive test scripts:
#!/bin/bash
# test/test.sh
set -e
echo "Testing plugin functionality..."
# Install plugin locally
mise plugin install my-plugin .
# Test basic functionality
if [[ "$(mise ls-remote my-plugin)" == "" ]]; then
echo "ERROR: No versions available"
exit 1
fi
# Test installation
mise install my-plugin@latest
# Test execution
mise exec my-plugin:tool -- --version
# Clean up
mise plugin remove my-plugin
echo "All tests passed!"
Test your plugin manually:
# Link for development
mise plugin link my-plugin /path/to/plugin
# Test all functionality
mise ls-remote my-plugin
mise install my-plugin@latest
mise use my-plugin@latest
# Test in different environments
docker run --rm -it ubuntu:latest bash -c "
curl -fsSL https://mise.en.dev/install.sh | sh
mise plugin install my-plugin https://github.com/username/my-plugin
mise install my-plugin@latest
"
Before publishing, ensure everything is ready:
# Run tests
./test/test.sh
# Check git status
git status
# Update version in metadata.lua
vim metadata.lua
# Commit changes
git add .
git commit -m "Prepare release v1.2.3"
Create a tagged release:
# Create and push tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3
git push origin main
Create a GitHub release for better discoverability:
## Changes in v1.2.3
### Added
- New feature X
- Support for Y
### Changed
- Improved performance of Z
- Updated dependencies
### Fixed
- Fixed issue with A
- Resolved bug in B
### Installation
```bash
mise plugin install my-plugin https://github.com/username/my-plugin
```
Users can install directly from your repository:
# Install from GitHub
mise plugin install my-plugin https://github.com/username/my-plugin
# Install specific version
mise plugin install my-plugin https://github.com/username/[email protected]
# Install from other Git providers
mise plugin install my-plugin https://gitlab.com/username/my-plugin
For private repositories, users need access:
# SSH access (recommended)
mise plugin install my-plugin [email protected]:username/private-plugin.git
# HTTPS with token
mise plugin install my-plugin https://username:[email protected]/username/private-plugin.git
You can also distribute as archives:
# Create release archive
git archive --format=zip --output=my-plugin-v1.2.3.zip v1.2.3
# Users can install from archive
mise plugin install my-plugin https://github.com/username/my-plugin/releases/download/v1.2.3/my-plugin-v1.2.3.zip
Establish a regular update process:
# Development workflow
git checkout -b feature/new-feature
# ... make changes ...
git commit -m "Add new feature"
git push origin feature/new-feature
# After review and merge
git checkout main
git pull origin main
git tag -a v1.3.0 -m "Release v1.3.0"
git push origin v1.3.0
Maintain backward compatibility when possible:
Keep users informed about updates:
Plugin not installing:
# Check repository URL
git clone https://github.com/username/my-plugin.git
# Verify metadata.lua exists
ls -la my-plugin/metadata.lua
# Test locally
mise plugin link my-plugin ./my-plugin
Version conflicts:
# Check version in metadata.lua
grep version my-plugin/metadata.lua
# Verify git tags
git tag -l
Permission issues:
# Check repository permissions
git ls-remote https://github.com/username/my-plugin.git
# For private repos, verify access
ssh -T [email protected]
# 1. Prepare plugin
cd my-backend-plugin
echo "Updated backend methods" > metadata.lua
# 2. Test locally
mise plugin link my-plugin .
mise ls-remote my-plugin:tool
# 3. Release
git add .
git commit -m "v1.0.0: Initial release"
git tag -a v1.0.0 -m "Initial release"
git push origin v1.0.0
# 1. Prepare plugin
cd my-tool-plugin
./test/test.sh # Run tests
# 2. Update version
sed -i 's/version = "1.0.0"/version = "1.1.0"/' metadata.lua
# 3. Release
git add .
git commit -m "v1.1.0: Add new hook functionality"
git tag -a v1.1.0 -m "Add new hook functionality"
git push origin v1.1.0