How to Create and Publish Your Widgets (Official Guide)

[osmn-byhn]

📢 Announcement: How to Create and Publish Your Widgets (Official Guide)

Welcome to the Web Widgets Community! 🧩

To ensure our ecosystem remains secure, high-quality, and easy to maintain, we have standardized the process for creating and publishing new widgets for the Kurug engine.

Whether you are a core maintainer or a new contributor, all new widgets must follow the steps and security protocols outlined below.

---

🛠️ Step 1: Use the Official Widget Template

We have created a standardized template repository that includes the basic folder structure and the mandatory Continuous Integration (CI) workflows. You must use this template to start your project.

1. Go to our official template: widget-template
2. Click the green "Use this template" button (and select Create a new repository).
3. Choose web-widgets-community as the owner (or your personal account if you plan to transfer it later).

📦 Step 2: Naming Convention

Please name your new repository using the following format:
widget-<your-widget-name>
(Example: widget-weather-app, widget-clock, widget-system-monitor)

🔒 Step 3: Automated Security & Quality Checks (CI/CD)

When you use the template, it automatically includes a .github/workflows/ci.yml file. This is our automated security and code quality gatekeeper.

How it works:

• We have a strict, centralized "Constitution" for security.
• To prevent malicious code (like XSS, cookie theft, or unauthorized background downloads), widgets are strictly forbidden from using functions like eval(), fetch(), XMLHttpRequest, or accessing document.cookie.
• Every time you push code, our GitHub Actions will automatically download the organization's central .eslintrc.json ruleset and scan your code.
• If your code contains forbidden elements or syntax errors, the test will fail.

🛡️ Step 4: Branch Protection & Pull Requests

To protect the integrity of the widgets, the main (or master) branch of every repository in this organization is strictly protected.

• No Direct Commits: You cannot push code directly to the main branch.
• Open a Pull Request (PR): You must create a new branch for your feature or widget, and then open a PR against main.
• Required Status Checks: Your PR cannot be merged until the ESLint & Prettier and Security Vulnerability Scan actions pass successfully (Green checkmarks ✅).
• Code Review: All PRs require at least one approval from a maintainer, and all conversation threads must be marked as "Resolved" before merging.
• Linear History: We require a clean commit history. Only Squash or Rebase merges are allowed.

---

🚀 Ready to Build?

By following these steps, you help us keep the Kurug desktop experience safe and beautiful for everyone. If you encounter any issues with the template or the automated tests, please open a discussion in the community repo!

Keep coding, reinvent your desktop! 💻✨