TortoiseSVN là gì? Hướng dẫn dùng TortoiseSVN để submit plugin lên WordPress.org

TortoiseSVN là gì?

TortoiseSVN là một phần mềm client SVN (Subversion) chạy trên Windows, tích hợp trực tiếp vào File Explorer thông qua menu chuột phải. Thay vì phải gõ lệnh trong terminal, bạn có thể checkout, commit, update, add, delete, resolve conflict… bằng giao diện trực quan.

SVN là gì và tại sao WordPress.org dùng SVN?

SVN (Apache Subversion) là một hệ thống quản lý phiên bản (version control) tương tự Git, nhưng ra đời sớm hơn và theo mô hình trung tâm (centralized). WordPress.org vẫn sử dụng SVN cho kho plugin/theme vì:

• Quy trình phát hành phiên bản và tagging của SVN phù hợp với cách WordPress.org quản lý bản release.
• Hệ thống build/hiển thị plugin trên WordPress.org được thiết kế xoay quanh cấu trúc SVN tiêu chuẩn.
• Nhiều tác giả plugin lâu năm đã quen với SVN và quy trình kiểm duyệt hiện tại.

Lợi ích khi dùng TortoiseSVN cho plugin WordPress

• Dễ dùng: thao tác bằng menu chuột phải, thấy rõ file nào thay đổi.
• Giảm sai sót: có hộp thoại kiểm tra danh sách file trước khi commit.
• Quản lý release rõ ràng: dùng trunk/tags theo chuẩn WordPress.org.
• Phù hợp Windows: không cần cài môi trường dòng lệnh phức tạp.

Chuẩn bị trước khi submit plugin lên WordPress.org

• Tài khoản WordPress.org (đăng ký và xác thực email).
• Plugin đã sẵn sàng: mã nguồn ổn, tuân thủ guideline, không chứa mã độc, không nhồi nhét link.
• File readme.txt theo chuẩn WordPress (rất quan trọng cho SEO trong kho plugin).
• Phiên bản trong readme.txt và trong file chính của plugin cần đồng bộ.
• TortoiseSVN đã cài trên máy (kèm SVN command line client nếu trình cài đặt có hỏi).

Cấu trúc SVN chuẩn của plugin WordPress.org

Khi plugin được duyệt và bạn được cấp kho SVN, cấu trúc tiêu chuẩn sẽ là:

• trunk/: nơi chứa mã nguồn đang phát triển và cũng thường là nơi “bản mới nhất” được lấy ra nếu bạn chưa tạo tag.
• tags/: chứa các bản phát hành theo phiên bản, ví dụ tags/1.0.0, tags/1.0.1.
• branches/: ít dùng với plugin nhỏ, thường dùng cho nhánh bảo trì.

Ví dụ thực tế: các bước submit plugin lên WordPress.org bằng TortoiseSVN

Bước 1: Gửi plugin để xét duyệt và nhận thông tin SVN

Bạn vào trang Add New Plugin trên WordPress.org, upload file ZIP plugin để xét duyệt. Sau khi được duyệt, bạn sẽ nhận email chứa:

• URL kho SVN (dạng: https://plugins.svn.wordpress.org/ten-plugin/)
• Hướng dẫn cơ bản về cấu trúc trunk/tags

Lưu ý: username/password chính là tài khoản WordPress.org của bạn.

Bước 2: Checkout kho SVN về máy bằng TortoiseSVN

1. Tạo một thư mục trống trên máy, ví dụ: D:\wp-svn\ten-plugin.
2. Chuột phải vào thư mục đó > chọn SVN Checkout….
3. Dán URL SVN repo: https://plugins.svn.wordpress.org/ten-plugin/.
4. Nhấn OK để checkout. Nếu yêu cầu đăng nhập, nhập tài khoản WordPress.org.

Sau khi checkout xong, bạn sẽ thấy các thư mục trunk, tags, assets, branches (có thể trống tùy repo).

Bước 3: Đưa mã nguồn plugin vào trunk

1. Mở thư mục trunk.
2. Copy toàn bộ mã nguồn plugin của bạn vào trunk (không copy file ZIP, chỉ copy file/folder của plugin).
3. Đảm bảo cấu trúc plugin chuẩn, ví dụ:
   • trunk/ten-plugin.php (file chính)
   • trunk/readme.txt
   • trunk/includes/, trunk/assets/…

Bước 4: Add các file mới vào SVN (rất hay bị quên)

SVN không tự động theo dõi file mới. Bạn cần add trước khi commit:

1. Chuột phải trong thư mục trunk > chọn TortoiseSVN > Add….
2. Chọn các file/folder cần add (thường là tất cả file mới) > nhấn OK.

Mẹo thực tế: Nếu bạn lỡ copy quá nhiều thứ rác (node_modules, vendor nặng, file build tạm), hãy loại chúng ra trước khi add/commit.

Bước 5: Kiểm tra readme.txt và version trước khi commit

Đây là chỗ “toang” nhiều nhất khi submit lên WordPress.org. Trước khi commit, bạn nên kiểm tra:

• Stable tag trong readme.txt có hợp lý (thường là phiên bản bạn sắp phát hành, ví dụ: 1.0.0).
• Version trong header file chính của plugin khớp với release.
• Changelog có ghi rõ thay đổi.
• Nếu có Requires at least, Tested up to, Requires PHP thì điền đúng để tăng độ tin cậy và SEO trong kho plugin.

Bước 6: Commit lần đầu lên trunk

1. Chuột phải thư mục plugin (repo đã checkout) > chọn SVN Commit….
2. Viết message commit rõ ràng, ví dụ: Initial commit to trunk.
3. Kiểm tra danh sách file sẽ commit (tránh commit file thừa) > nhấn OK.

Sau commit, WordPress.org sẽ cần một khoảng thời gian để đồng bộ hiển thị plugin. Nếu readme.txt đúng chuẩn, trang plugin sẽ bắt đầu xuất hiện.

Bước 7: Tạo tag phiên bản phát hành trong tags

Quy trình chuẩn khi phát hành là: commit code vào trunk trước, rồi copy trunk sang tags/x.y.z.

1. Vào thư mục repo của bạn, chuột phải > chọn Branch/Tag… (trong TortoiseSVN).
2. Ở phần “To URL”, chọn đường dẫn tag, ví dụ: https://plugins.svn.wordpress.org/ten-plugin/tags/1.0.0.
3. Chọn nguồn là trunk (thường tool sẽ tự hiểu bạn đang tag từ trunk).
4. Nhập message, ví dụ: Tagging version 1.0.0 > nhấn OK.

Sau khi tag, nếu trong readme.txt bạn đặt Stable tag: 1.0.0 thì WordPress.org sẽ lấy bản trong tags/1.0.0 làm bản ổn định để phát hành.

Bước 8: Upload banner/icon/screenshot đúng chuẩn (assets)

Để trang plugin nhìn “xịn” và tăng tỷ lệ cài đặt, bạn nên thêm asset. WordPress.org dùng thư mục đặc biệt /assets ở root của repo SVN (cùng cấp với trunk/tags/branches), không phải trunk/assets.

• banner-772×250.png hoặc banner-1544×500.png
• icon-128×128.png hoặc icon-256×256.png
• screenshot-1.png, screenshot-2.png…

Quy trình:

1. Tạo thư mục assets ở root repo nếu chưa có.
2. Copy file ảnh vào đó.
3. Add > Commit tương tự trunk.

Lưu ý: phần mô tả screenshot thường khai báo trong readme.txt, mục Screenshots để WordPress.org hiển thị đúng thứ tự.

Bước 9: Cập nhật phiên bản mới (ví dụ 1.0.1) đúng quy trình

1. Sửa code trong trunk, tăng version trong file plugin và readme.txt.
2. SVN Commit trunk với message kiểu: Release 1.0.1 changes.
3. Tạo tag mới: tags/1.0.1 bằng Branch/Tag….
4. Đảm bảo Stable tag trỏ tới 1.0.1 (hoặc để “trunk” nếu bạn phát hành trực tiếp từ trunk, nhưng cách này ít “đẹp” hơn).

Lỗi thường gặp khi submit plugin bằng TortoiseSVN và cách tránh

• Quên Add file mới: file copy vào trunk nhưng không add, commit xong lên server thiếu file. Cách tránh: luôn chạy Add trước, hoặc mở Commit dialog và kiểm tra file trạng thái.
• Nhét nhầm thư mục gốc: nhiều bạn copy cả folder plugin vào trunk thành trunk/ten-plugin/ten-plugin.php. Cách tránh: đảm bảo file chính nằm trực tiếp trong trunk.
• Stable tag sai: stable tag trỏ phiên bản chưa có trong tags. Cách tránh: tag xong mới cập nhật stable tag, hoặc đồng bộ cả hai.
• Commit file thừa: node_modules, file build tạm, .env. Cách tránh: dọn sạch trước khi add/commit, và kiểm tra kỹ danh sách commit.
• Conflict khi update: thường do bạn sửa trực tiếp trên máy trong khi repo có thay đổi. Cách xử lý: SVN Update thường xuyên và dùng Resolve nếu cần.

Mẹo SEO cho trang plugin WordPress.org (tận dụng readme.txt)

• Viết Short Description rõ lợi ích, chứa keyword chính.
• Phần Description nên có cấu trúc, có heading dạng đơn giản, nêu use-case cụ thể.
• Chèn FAQ chất lượng để tăng độ tin cậy và giữ người đọc.
• Changelog cập nhật đều giúp người dùng cảm thấy plugin “còn sống”.
• Ảnh banner/icon chuyên nghiệp giúp tăng CTR trong trang kho plugin.

Kết luận

TortoiseSVN là lựa chọn cực hợp lý nếu bạn phát triển plugin trên Windows và muốn đưa plugin lên WordPress.org theo đúng chuẩn SVN. Chỉ cần nhớ “xương sống” của quy trình là: checkout repo, đưa code vào trunk, add file mới, commit, rồi tag phiên bản trong tags. Làm đúng nhịp này thì mỗi lần release sẽ gọn, sạch và ít drama hơn nhiều.