neiam /home-assistant-plasmoid

Home Assistant Plasmoid

public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages

Reorganize documentation: Move publishing info to separate PUBLISHING.md file

c44eef2 · gmorell · 2025-06-26 03:50

2 files +173 -0

Message

{commit_body(@commit)}

Files changed

added PUBLISHING.md

+163 −0

@@ -0,0 +1,163 @@

	1	+# Publishing & Development Automation
	2	+
	3	+This repository includes automated workflows for packaging and releasing the Home Assistant plasmoid to the KDE Store.
	4	+
	5	+## 🚀 Automated Release Process
	6	+
	7	+### Creating a Release
	8	+
	9	+Method 1: Git Tags (Recommended)
	10	+```bash
	11	+git tag v2.1
	12	+git push origin v2.1
	13	+```
	14	+
	15	+Method 2: Manual Trigger
	16	+1. Go to repository Actions tab on GitHub
	17	+2. Select "Create Plasmoid Release"
	18	+3. Click "Run workflow"
	19	+4. Enter version number
	20	+5. Click "Run workflow"
	21	+
	22	+### What Happens Automatically
	23	+
	24	+1. ✅ Package Creation: Creates `.tar.gz` and `.zip` files
	25	+2. ✅ Version Update: Updates `metadata.json` with new version
	26	+3. ✅ GitHub Release: Creates release with download links
	27	+4. ✅ Upload Instructions: Provides step-by-step KDE Store guide
	28	+
	29	+## 🏪 Publishing to KDE Store
	30	+
	31	+After automation completes:
	32	+
	33	+1. Download the `.tar.gz` file from GitHub release
	34	+2. Login to [store.kde.org](https://store.kde.org)
	35	+3. Navigate to your plasmoid page
	36	+4. Add new version and upload the package
	37	+5. Publish the update
	38	+
	39	+## 🧪 Local Development
	40	+
	41	+### Local Packaging
	42	+```bash
	43	+# Create development package
	44	+./package.sh
	45	+
	46	+# Create specific version
	47	+./package.sh 2.1
	48	+```
	49	+
	50	+### Testing Installation
	51	+```bash
	52	+# Install locally for testing
	53	+kpackagetool6 --type Plasma/Applet --install home-assistant-plasmoid-2.0.tar.gz
	54	+
	55	+# Remove after testing
	56	+kpackagetool6 --type Plasma/Applet --remove org.neiam.kde.homeassistant
	57	+```
	58	+
	59	+## 🔧 Workflow Configuration
	60	+
	61	+### Repository Setup
	62	+
	63	+The workflows require GitHub repository permissions:
	64	+
	65	+1. Go to Settings → Actions → General
	66	+2. Under "Workflow permissions":
	67	+ - Select "Read and write permissions"
	68	+ - Check "Allow GitHub Actions to create and approve pull requests"
	69	+3. Click Save
	70	+
	71	+### Available Workflows
	72	+
	73	+1. Release Workflow (`.github/workflows/release.yml`)
	74	+ - Triggers: Git tags starting with `v`
	75	+ - Creates packages and GitHub releases
	76	+ - Provides KDE Store upload instructions
	77	+
	78	+2. Validation Workflow (`.github/workflows/validate.yml`)
	79	+ - Triggers: Push to main branches, PRs
	80	+ - Validates plasmoid structure and metadata
	81	+ - Checks QML syntax and package integrity
	82	+
	83	+## 📋 Best Practices
	84	+
	85	+### Version Management
	86	+- Use semantic versioning: `v1.0.0`, `v1.1.0`, `v2.0.0`
	87	+- Update version in `metadata.json` before tagging
	88	+- Write meaningful commit messages for changelog
	89	+
	90	+### Pre-Release Checklist
	91	+- [ ] Test plasmoid functionality locally
	92	+- [ ] Update README with new features
	93	+- [ ] Verify metadata.json version
	94	+- [ ] Run `./package.sh` to test packaging
	95	+- [ ] Check QML syntax and structure
	96	+
	97	+### Release Process
	98	+1. Development: Make changes and test locally
	99	+2. Commit: Push changes to main branch
	100	+3. Validation: Ensure validation workflow passes
	101	+4. Tag: Create version tag to trigger release
	102	+5. Upload: Download package and upload to KDE Store
	103	+
	104	+## 🐛 Troubleshooting
	105	+
	106	+### GitHub Actions Issues
	107	+
	108	+403 Permission Error:
	109	+- Update repository workflow permissions (see above)
	110	+- Ensure workflows have `permissions: contents: write`
	111	+
	112	+Package Creation Fails:
	113	+- Check required files exist (`metadata.json`, `contents/ui/main.qml`)
	114	+- Verify JSON syntax in metadata.json
	115	+- Review workflow logs for specific errors
	116	+
	117	+Release Creation Fails:
	118	+- Verify tag format starts with `v` (e.g., `v2.0`)
	119	+- Check repository permissions
	120	+- Ensure no existing release with same tag
	121	+
	122	+### Local Packaging Issues
	123	+
	124	+Script Fails:
	125	+- Ensure `rsync` is installed
	126	+- Check file permissions (`chmod +x package.sh`)
	127	+- Verify no syntax errors in script
	128	+
	129	+Package Too Large:
	130	+- Review included files (check `.gitignore`)
	131	+- Remove unnecessary development files
	132	+- Optimize images and assets
	133	+
	134	+### KDE Store Upload Issues
	135	+
	136	+Wrong Package Format:
	137	+- Use `.tar.gz` file, not `.zip`
	138	+- Ensure proper directory structure inside package
	139	+
	140	+Version Conflicts:
	141	+- Ensure version number is unique
	142	+- Match version in `metadata.json` and store
	143	+
	144	+Metadata Issues:
	145	+- Validate JSON syntax
	146	+- Ensure all required KPlugin fields present
	147	+- Check icon and category specifications
	148	+
	149	+## 📖 Additional Resources
	150	+
	151	+- [KDE Store Documentation](https://store.kde.org)
	152	+- [Plasma Applet Development Guide](https://develop.kde.org/docs/plasma/applets/)
	153	+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
	154	+- [KDE Community Resources](https://community.kde.org)
	155	+
	156	+## 🔄 Future Enhancements
	157	+
	158	+The automation system can be extended with:
	159	+- Automated changelog generation from commits
	160	+- Integration testing in different Plasma versions
	161	+- Automated screenshots for store listings
	162	+- Multi-platform package generation
	163	+- Automated dependency checking

modified README.md

+10 −0

@@ -220,3 +220,13 @@ This widget is open source. Feel free to contribute improvements:

220	220	- Additional control types
221	221	- UI/UX improvements
222	222	- Performance optimizations
	223	+
	224	+---
	225	+
	226	+## 🚀 Automated Publishing
	227	+
	228	+This repository includes GitHub Actions for automated packaging and release management. See [PUBLISHING.md](PUBLISHING.md) for details on:
	229	+- Automated KDE Store package creation
	230	+- Release management with git tags
	231	+- Local development and testing tools
	232	+- Deployment workflow documentation

Parents: f9f95f7