Publishing your first WordPress Plugin with GIT and SVN

When publishing your plugin to the official WordPress repository, you HAVE to use SVN. As for September 2019, WordPress doesn’t support GIT repos.

Using SVN instead of GIT (as your code version control) wouldn’t be more than a mere inconvenience if wasn’t for the fact that WordPress’ SVN is not meant to be used as a code version control. You need to use something else for this.

From WordPress’ official page:

SVN and the Plugin Directory are a release repository. Unlike Git, you shouldn’t commit every small change, as doing so can degrade performance. Please only push finished changes to your SVN repository.

So, if you want to have a code version control (you should have one), you need to set it up separately. Even if you like SVN more than GIT, you must set an additional SVN repo just for your code version control. You can’t use WordPress’ SVN for code control.


In this tutorial, I will show you how to use GIT and SVN together, in an organized way. GIT for code control and SVN for publishing only.

1. Your current development structure:

I am 100% sure you are working in a structure like this:


my-project
└── wp-content
    └── plugins
        └── my-plugin
            └── my-plugin.php

The my-project folder is a full WordPress installation, used as a shell for your plugin development.

my-plugin is your actual plugin folder. It’s where all development happens.

And obviously, my-plugin/my-plugin.php is the plugin’s entry-point.

2. The plan:

Our final folder structure will be:


my-project
├── working-env
│   └── wp-content
│       └── plugins
│           └── my-plugin
│               ├── .git
│               └── my-plugin.php
└── svn
    ├── assets
    ├── branches
    ├── tags
    └── trunk
        ├── .git
        └── my-plugin.php

The working-env folder is our WP instance, just renamed. It is still where we do all our work. Notice that we have initialized GIT on my-plugin, which means the plugin folder is the only thing on GIT. We don’t need to keep the whole WP instance on version control nor make backups of it. In case we need to restore the project (ex. install it in a new machine), we re-create “working-env” from a brand new WP installation and clone the GIT repo in the “my-plugin” folder.

The svn folder is only used for deployment. It has the 4 standard SVN folders: assets, branches, tags, and trunk. This structure is automatically generated by WordPress once we clone the SVN repository. We don’t need to keep this folder on GIT nor make backups of it. Even if we destroy the entire “svn” folder, we can always restore it from the SVN repo. A quick explanation about its structure: the assets folder contains images displayed on the plugin’s page (screenshots, banners and plugin icon). The trunk folder is the current stable version that is available for download on WP.

The workflow is: we work on “my-plugin” (“working-env”) and once is tested and ready for deploy, we update the “trunk” folder (with “my-plugin” files), and we call the svn command to submit.

3. Preparing your code for publishing:

Once your first version is tested and ready to be published, we need to set up the readme.txt file (as per WP’s official guide).

We don’t have our GIT and SVN set up yet, but don’t worry – we will do after preparing our code for publishing.

2.1. Know the rules:

Read the rules for publishing. It only takes a few seconds and you will discover a lot of things that are not allowed (like having a jQuery library on your plugin):
https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/

2.2. Choosing a name:

Our plugin must have a name and it must follow these rules:

  • Must be unique: Check the WP plugin directory to see if there’s another plugin with the same name as yours.
  • Trademark infringement: Do not use trademarks like “Facebook” in your plugin’s name. It is not allowed. For example, “Facebook Sign-Up” is not okay. If you really want to put a trademark on the name, read rule #17 – there are some ways to do it.
  • Bad words: Not allowed at all.
  • You can’t rename the plugin: So choose the name wisely.

2.3. Edit readme.txt (most IMPORTANT step!!!)

Before publishing your plugin, you MUST edit the readme.txt file. It seems a silly thing to do, but this file actually governs many aspects of the plugin.

The readme file defines the plugin name, version and other control information used for updates and repository management. This file is also the first thing the users will see when looking for plugins on the WP directory (description, screenshots, etc).

If you created your plugin with WP-CLI, you should have a “readme.txt” file with a full example ready to be edited.

Important fields you NEED to set:

  • Version (stable tag): Same as in “my-plugin.php” headers (ex. “0.1.0”);
  • License (ex. MIT, GPL2, etc): Must be a GPL-compatible license;
  • Changelog: Set a “0.1.0: First version”;
  • Screenshots: NO SCREENSHOTS for now – just remove this section (even if you have it, we can only define this section AFTER submitting our plugin for the first time);
  • Plugin name / Short description / Long description, Author (contributors): Your moment to shine.

For a complete list of all fields (and for a full example):
https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/

Test your final “readme.txt” file here:
https://wordpress.org/plugins/developers/readme-validator/

3. Create an SVN repository on WordPress:

Once your readme.txt is ready, let’s create an empty SVN repository on WordPress:

  • ZIP your plugin files (except the .git folder if exists);
  • Name it as my-plugin.zip (change “my-plugin” to your plugin’s name);
  • Test the ZIP file by manually installing the plugin into a different WP installation (Plugins > Add New > Upload Plugin > my-plugin.zip);
  • Submit your ZIP file to review: https://wordpress.org/plugins/developers/add/

It can take a few days for your plugin be reviewed. Once approved, you will receive SVN credentials on your email.

Once approved, the SVN repo will be empty. They won’t prefill it with your plugin.

4. Setting GIT:

While you wait your plugin be approved, let’s set GIT on wp-content/plugins/my-plugin.

Gitignore:

If you have used wp-cli, you don’t need to do anything: there will be a .gitignore in your folder. If you haven’t used it, then you will need one:


.DS_Store
phpcs.xml
phpunit.xml
Thumbs.db
wp-cli.local.yml
node_modules/
*.sql
*.tar.gz
*.zip

Init your git repo locally:


cd wp-content/plugins/my-plugin
git init
git add -a
git commit -m "my first commit"

On GitHub (GitLab, etc), create a repo, submit the files (follow the second set of instructions, “Push an existing repository…”):


cd wp-content/plugins/my-plugin
(out)
git remote add origin [email protected]:username/new_repo
git push -u origin master

5. Move your WP installation from my-project to my-project\working-env:


mv my-project working-env
mkdir my-project
mv working-env my-project

Check the structure:


cd my-project
ls
(out)working-env

6. Clone your SVN (it will be empty – they won’t pre-fill it for you with your zip files):

Once the plugin has been approved and you get the SVN credentials on your email:


cd my-project
(out)
mkdir svn
svn co https://plugins.svn.wordpress.org/your-plugin-name svn

Structure of my-project/svn:


/assets/
/branches/
/tags/
/trunk/

7. Ignore .git folder on SVN:

  1. Edit ~/.subversion/config
  2. Look for the miscellany section, uncomment “global-ignores“, make sure “.git” is there (also “.env” if you use it to store sensitive information):

[miscellany]
global-ignores = *.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo __pycache__ .git .gitignore .env

8. [Optional] Add a screenshot to the plugin’s page:

Steps:

  • Take a screenshot (any size, ex. 760×500);
  • Save the file on “svn/assets”;
  • File name must be:
    • screenshot-1.jpg (or png)
    • screenshot-2.jpg (or png)

Change readme.txt:


== Screenshots ==

1. This is a screenshot description
2. This is a description for the second screenshot

Official Guide:
https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/#screenshots

9. [Optional] Add Icon and Banner to the plugin page:

Icon (official guide here):

  • Put on “/assets” folder;
  • Set filename accordingly (ex. icon-256x256.png – see guide for different formats)
  • No need for readme.txt changes.

Banner:
https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/#plugin-headers

10. [FINAL STEP] Submit plugin:

Go to the project root:


cd my-project

Update svn/trunk with your most recent files (my-plugin):


rm -Rf svn/trunk
cp -R working-env/wp-content/plugins/my-plugin svn/trunk

Make sure .git/.gitignore is not going to be submitted:


svn stat

Submit your SVN for the first time:


cd svn
svn add trunk/*
svn ci -m 'Adding first version of my plugin'

Congratulations! Your plugin is now publicly available for download.


Updating your plugin (with a new version):

Do your changes on working-env and test them. Once you are ready, you can proceed.

Update the version:

In this example, let’s change the version from 1.0.0 to 1.0.1.

Change 2 files: readme.txt and my-plugin.php. Don’t forget to add a Changelog entry on “readme.txt”.

Push to GIT:

Go to my-plugin folder:


cd working-env/wp-content/plugins/my-plugin

Add files, commit, and push:


git add -i
git commit -m "some changes"
git push origin master

Submit the new code:

Go to the project root:


cd my-project

Update svn/trunk with your most recent files (my-plugin):


rm -Rf svn/trunk
cp -R working-env/wp-content/plugins/my-plugin svn/trunk

Make sure .git/.gitignore is not going to be submitted:


svn stat

Copy “trunk” to “tags” using the svn command:


svn cp trunk tags/1.0.1

Submit the new version:


svn ci -m "tagging version 1.0.1"

Getting Support Notifications For Your Plugin

To receive email notifications when your users submit support requests:

  1. Open your plugin page (ex. https://wordpress.org/plugins/user-export-with-their-meta-data)
  2. Click on the “Support” tab:

3. Click on “Subscribe to this plugin”:

Done!

Close Menu