Cách tạo và submit plugin WordPress lên .org: Hướng dẫn từ A đến Z (kèm checklist)

Bài viết này hướng dẫn toàn bộ quy trình phát hành plugin WordPress lên WordPress.org Plugin Directory, dành cho developer muốn đưa sản phẩm của mình đến hàng triệu người dùng.

Checklist tóm tắt

• Kiểm tra plugin headers và readme.txt
• Code quality: PHPCS, PHP 8.x compatible
• CI pass trên GitHub Actions
• Branch workflow: feature → develop → master
• Tạo GitHub Release + build ZIP sạch
• Deploy lên WP.org SVN (nếu có)
• Verify sau release

1. Chuẩn bị trước khi release

1.1 Plugin headers

File chính của plugin cần khai báo đầy đủ thông tin phiên bản:

// my-plugin.php
/*
 * Version:           2.7.0
 * Requires at least: 6.0
 * Requires PHP:      8.0
 */
define( 'MY_PLUGIN_VERSION', '2.7.0' );

1.2 readme.txt

File readme.txt là nơi WordPress.org đọc thông tin plugin. Cần đúng định dạng:

=== Plugin Name ===
Contributors: yourusername
Tags: tag1, tag2
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 2.7.0
License: GPLv2 or later

== Description ==
Mô tả ngắn gọn về plugin.

== Changelog ==
= 2.7.0 =
* Tính năng mới
* Sửa lỗi

2. Kiểm tra chất lượng code

# PHPCS kiểm tra coding standard
composer lint

# Kiểm tra thủ công trên WP thật:
# - Kích hoạt không lỗi
# - Tắt plugin sạch
# - Không có PHP warning/deprecation
# - Các settings page hiển thị đúng

Trong quá trình phát triển các plugin WordPress tại Code Tốt, đội ngù luôn duy trì CI/CD trên GitHub Actions với ma trận PHP 8.0–8.4 để đảm bảo tương thích. Hai dự án đã được publish lên WordPress.org là SSO for Microsoft Entra và CT Optimization.

3. Branch workflow

Feature branch → PR → develop → PR → master

git checkout develop
git checkout -b feat/my-feature
# ... code changes ...
gh pr create --base develop --head feat/my-feature
# Sau review: merge vào develop
gh pr create --base master --head develop
# Merge vào master khi approved

4. Tạo GitHub Release

WordPress.org yêu cầu file ZIP chỉ chứa mã nguồn plugin, không kèm .git, .github, composer.json hay các file dev.

# Tạo tag
git checkout master
git pull origin master
git tag v2.7.0
git push origin v2.7.0

# Build ZIP sạch
cd /tmp
git clone --branch v2.7.0 --depth 1 [email protected]:{org}/{repo}.git {slug}
cd {slug}
rm -rf .git .github .gitignore composer.* node_modules tests docs
cd /tmp
zip -r {slug}-v2.7.0.zip {slug}/

# Upload lên GitHub Release
gh release create v2.7.0 --title "v2.7.0" --notes "See CHANGELOG.md"
gh release upload v2.7.0 /tmp/{slug}-v2.7.0.zip

5. Deploy lên WordPress.org (SVN)

Sau khi plugin được duyệt trên WordPress.org, bạn có thể tự động deploy qua GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy to WordPress.org

on:
  release:
    types:
      - published

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to WP.org
        uses: 10up/action-wordpress-plugin-deploy@stable
        env:
          SVN_USERNAME: \${{ secrets.SVN_USERNAME }}
          SVN_PASSWORD: \${{ secrets.SVN_PASSWORD }}
          SLUG: {plugin-slug}
          ASSETS_DIR: .wordpress-org

Cấu hình GitHub Secrets:

• SVN_USERNAME — WordPress.org username
• SVN_PASSWORD — Application Password (tạo từ WP.org profile)

6. Assets cho WP.org

Thư mục .wordpress-org/ chứa icon và banner cho plugin page:

7. Kiểm tra sau release

• SVN trunk và tag đã được tạo: svn ls https://plugins.svn.wordpress.org/{slug}/trunk/
• Plugin page hoạt động: https://wordpress.org/plugins/{slug}/
• Số phiên bản khớp với readme.txt
• Icon và banner hiển thị đúng
• Nút Download hoạt động
• Cài đặt trên WP sạch không lỗi

Tóm tắt quy trình nhanh

git checkout master && git pull
git tag v2.7.0 && git push origin v2.7.0

cd /tmp && git clone --branch v2.7.0 --depth 1 {repo} {slug}
cd {slug} && rm -rf .git .github composer.* node_modules tests
cd /tmp && zip -r {slug}-v2.7.0.zip {slug}/

gh release create v2.7.0 --title "v2.7.0" --notes "See CHANGELOG"
gh release upload v2.7.0 /tmp/{slug}-v2.7.0.zip

Tham khảo: WP.org Plugin Developer Docs | 10up Deploy Action | So sánh plugin cache