From 945b5a1bd454db61a90ee726031c64e78faf6899 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Wed, 15 May 2013 22:52:00 -0400 Subject: [PATCH 1/9] updating the README file related #48 --- README.md | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6b5aa78..4f103ed 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,35 @@ + # WordPress Plugin Boilerplate The WordPress Plugin Boilerplate serves as a foundation and aims to provide a clear and consistent guide for building your WordPress plugins. ## Features -* The Plugin Boilerplate is fully-based on the WordPress [Plugin API](http://codex.wordpress.org/Plugin_API) -* Uses [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) conventions for easily following the code -* Liberal use of `TODO` to guide you through what you need to change -* Uses a strict file organization scheme to make sure the assets are easily maintainable -* Note that this boilerplate uses `plugin.po` to provide a translation file. This is compatible with [POEdit](http://www.poedit.net/) +* The Plugin Boilerplate is fully-based on the WordPress [Plugin API](http://codex.wordpress.org/Plugin_API). +* Uses [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) conventions to document the code. +* Example values are given, so you can see what needs to be changed. +* Uses a strict file organization scheme to make sure the assets are easily maintainable. +* Note that this boilerplate includes a `.pot` as a starting translation file. ## Contents The WordPress Plugin Boilerplate includes the following files: -* This `README` -* A subdirectory called `plugin-boilerplate` +* This README, a ChangeLog, and a `gitignore` file. +* A subdirectory called `plugin-name` +## Installation -1. Copy the `plugin-boilerplate` directory into your `wp-content/plugins` directory +1. Copy the `plugin-name` directory into your `wp-content/plugins` directory 2. Navigate to the *Plugins* dashboard page -3. Locate the menu item that reads *TODO* +3. Locate the menu item that reads *Plugin Name* 4. Click on *Activate* -This will activate the WordPress Plugin Boilerplate. Because the Boilerplate has no real functionality, nothing will be added to WordPress; however, this demonstrates exactly how your plugin should behave as you're working with it. +This will activate the WordPress Plugin Boilerplate. Because the Boilerplate has no real functionality, nothing will be added to WordPress; however, this demonstrates exactly how your plugin should behave while you're working with it. -If you opt to uncomment Line 77 which contains the following line: +A new menu item will be added to the *Plugins* menu if you uncomment Line 71 in the class file which contains the following line: -`add_action( 'admin_menu', array( $this, 'plugin_admin_menu' ) );` - -Then a new menu item will be added to the *Plugins* menu. +`add_action( 'admin_menu', array( $this, 'add_plugin_admin_menu' ) );` ## License @@ -52,18 +52,15 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA ### Licensing -The WordPress Plugin Boilerplate is licensed under the GPL2+ or later; however, if you opt to use third-party frameworks -such as [Bootstrap](http://twitter.github.io/bootstrap/) in your work, then you should be aware of this: +The WordPress Plugin Boilerplate is licensed under the GPL v2 or later; however, if you opt to use third-party code that is not compatible with v2, then you may need to switch to using code that is GPL v3 compatible. -> The most likely occurrence of this issue is with Themes developed using Twitter Bootstrap. When reviewing such Themes, please be sure to check that, if the Theme is licensed under GPL, that the license specifies either unversioned GPL, or GPLv3.0. - -For reference, [here's the full conversation](http://make.wordpress.org/themes/2013/03/04/licensing-note-apache-and-gpl/). +For reference, [here's a discussion](http://make.wordpress.org/themes/2013/03/04/licensing-note-apache-and-gpl/) that covers the Apache 2.0 License used by [Bootstrap](http://twitter.github.io/bootstrap/). ## Assets The assets directory provides two files that are used to represent plugin header images. -When committing your work to the WordPress Plugin Repository, these files should reside in their own `assets` directory, not in the root of the plugin. The initaly repository will contain three directories: +When committing your work to the WordPress Plugin Repository, these files should reside in their own `assets` directory, not in the root of the plugin. The initial repository will contain three directories: 1. `branches` 2. `tags` @@ -76,8 +73,13 @@ You'll need to add an `assets` directory into the root of the repository. So the 3. `tags` 4. `trunk` -Next, copy the contents of the `assets` directory that are bundled with the Boilerplate into the root of the repository. This is how the WordPress Plugin Repository will retrieving the plugin header image. +Next, copy the contents of the `assets` directory that are bundled with the Boilerplate into the root of the repository. This is how the WordPress Plugin Repository will retrievie the plugin header image. -Of course, you'll want to customize the header images from the place holders that are provided with the boilerplate. +Of course, you'll want to customize the header images from the place holders that are provided with the Boilerplate. -For more, in-depth information about this, read [this post](http://make.wordpress.org/plugins/2012/09/13/last-december-we-added-header-images-to-the/) by Otto. +For more, in-depth information about this, read [this post](http://make.wordpress.org/plugins/2012/09/13/last-december-we-added-header-images-to-the/) by [Otto](https://twitter.com/Otto42). + +Plugin screenshots can be saved to one of two locations: + +* The traditional location is to keep them in the root of the plugin directory. This will increase the size of the download of the plugin, but make the images accessible for those who install it. +* Alternatively, you can save the screenshots in the `assets` directory, as well. The repository will look here for the screenshot files as well; however, they will not be included in the plugin download thus reducing the size of the plugin. \ No newline at end of file From 8ead067e396ac5bf888156df6cd49bc36f58b418 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Wed, 15 May 2013 22:55:21 -0400 Subject: [PATCH 2/9] updating the change log for 2.4 --- ChangeLog.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/ChangeLog.md b/ChangeLog.md index b7bf76f..7bd4161 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,16 @@ +## 2.4.0 (15 May 2013) + +* Renaming and updating references in the pot file to match the new file names +* Renaming all `display` files to `public` (i.e., `display.js` to `public.js`) +* Updating references in comments and in code to the plugin class files and plugin files +* Updating the way the plugin terminates execution if accessed directly +* Updating code comments, clearing extraneous whitespace +* Renaming files to be more consistent with the example name of the plugin +* Renaming 'plugin-boilerplate' to 'plugin-name' to be more consistent with the naming conventions of the class file +* Adding a sample screenshot to match the example WordPress Plugin Repository `readme.txt` +* Removing the plugin version constant in favor of a property in the plugin class +* Adding proper page-level DocBlocks + ## 2.3.0 (13 May 2013) * Moving the activation hooks outside of the class and marking the methods as static From 1c49f99e788d8e69c9d4941f3c7f5144e254c446 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:36:23 -0400 Subject: [PATCH 3/9] Updated to `readme.txt` to be up to standard with the current WordPress Plugin Repository demo Fixes #50 --- ChangeLog.md | 5 +++++ plugin-name/README.txt | 20 ++++++++++++-------- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 7bd4161..2a5d6c1 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,8 @@ +## 2.5.0 (16 May 2013) + +* Updated to `readme.txt` to be up to standard with the current WordPress Plugin Repository demo + + ## 2.4.0 (15 May 2013) * Renaming and updating references in the pot file to match the new file names diff --git a/plugin-name/README.txt b/plugin-name/README.txt index 3797795..94cb98c 100644 --- a/plugin-name/README.txt +++ b/plugin-name/README.txt @@ -1,10 +1,12 @@ === Plugin Name === -Contributors: username1, username2 (this should be a list of wordpress.org userid's) +Contributors: (this should be a list of wordpress.org userid's) Donate link: http://example.com/ Tags: comments, spam -Requires at least: 3.3.1 -Tested up to: 3.3.1 +Requires at least: 3.5.1 +Tested up to: 3.6 Stable tag: 1.0.0 +License: GPLv2 or later +License URI: http://www.gnu.org/licenses/gpl-2.0.html Here is a short description of the plugin. This should be no more than 150 characters. No markup here. @@ -58,24 +60,26 @@ Answer to foo bar dilemma. == Screenshots == 1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from -the directory of the stable readme.txt, so in this case, `/tags/4.3/screenshot-1.png` (or jpg, jpeg, gif) +the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets +directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png` +(or jpg, jpeg, gif). 2. This is the second screen shot == Changelog == -= 1.0.0 = += 1.0 = * A change since the previous version. * Another change. -= 0.5.0 = += 0.5 = * List versions from most recent at top to oldest at bottom. == Upgrade Notice == -= 1.0.0 = += 1.0 = Upgrade notices describe the reason a user should upgrade. No more than 300 characters. -= 0.0.5 = += 0.5 = This version fixes a security related bug. Upgrade immediately. == Arbitrary section == From d345f74c4dd1fbf4d3138f5eddf07fd54ed629fd Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:37:48 -0400 Subject: [PATCH 4/9] adding example.com to the plugin-name page-level docblock related #48 --- plugin-name/plugin-name.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugin-name/plugin-name.php b/plugin-name/plugin-name.php index 256295c..cd90e52 100644 --- a/plugin-name/plugin-name.php +++ b/plugin-name/plugin-name.php @@ -8,7 +8,7 @@ * @package PluginName * @author Your Name * @license GPL-2.0+ - * @link TODO + * @link example.com * * @wordpress-plugin * Plugin Name: TODO From b8c03c083a9cc2c04566a36c1b5132576bd5ec50 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:40:25 -0400 Subject: [PATCH 5/9] updating page-level docblocks to be consistent related #48 --- plugin-name/class-plugin-name.php | 4 ++-- plugin-name/plugin-name.php | 9 +++++---- plugin-name/uninstall.php | 6 +++--- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/plugin-name/class-plugin-name.php b/plugin-name/class-plugin-name.php index 3e88f30..f78fe4c 100644 --- a/plugin-name/class-plugin-name.php +++ b/plugin-name/class-plugin-name.php @@ -4,9 +4,9 @@ * * @package PluginName * @author Your Name - * @copyright 2013 Your Name or Company Name * @license GPL-2.0+ - * @link http://example.com/plugin-name + * @link example.com + * @copyright 2013 Your Name or Company Name */ /** diff --git a/plugin-name/plugin-name.php b/plugin-name/plugin-name.php index cd90e52..bd93f8a 100644 --- a/plugin-name/plugin-name.php +++ b/plugin-name/plugin-name.php @@ -5,10 +5,11 @@ * A foundation off of which to build well-documented WordPress plugins that also follow * WordPress coding standards and PHP best practices. * - * @package PluginName - * @author Your Name - * @license GPL-2.0+ - * @link example.com + * @package PluginName + * @author Your Name + * @license GPL-2.0+ + * @link example.com + * @copyright 2013 Your Name or Company Name * * @wordpress-plugin * Plugin Name: TODO diff --git a/plugin-name/uninstall.php b/plugin-name/uninstall.php index 16003da..32285ed 100644 --- a/plugin-name/uninstall.php +++ b/plugin-name/uninstall.php @@ -3,11 +3,11 @@ * Fired when the plugin is uninstalled. * * @package PluginName - * @author TODO + * @author Your Name * @license GPL-2.0+ - * @link TODO + * @link example.com + * @copyright 2013 Your Name or Company Name * @version 1.0.0 - * @since 1.0.0 */ // If uninstall, not called from WordPress, then exit From bfc094ec687ae155b02a1f7e4070a0c007e57911 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:41:58 -0400 Subject: [PATCH 6/9] continuing to update all page-level docblocks for consistency related #48 --- plugin-name/uninstall.php | 9 ++++----- plugin-name/views/admin.php | 10 +++++----- plugin-name/views/public.php | 12 +++++------- 3 files changed, 14 insertions(+), 17 deletions(-) diff --git a/plugin-name/uninstall.php b/plugin-name/uninstall.php index 32285ed..d8ed8d4 100644 --- a/plugin-name/uninstall.php +++ b/plugin-name/uninstall.php @@ -2,12 +2,11 @@ /** * Fired when the plugin is uninstalled. * - * @package PluginName - * @author Your Name - * @license GPL-2.0+ - * @link example.com + * @package PluginName + * @author Your Name + * @license GPL-2.0+ + * @link http://example.com * @copyright 2013 Your Name or Company Name - * @version 1.0.0 */ // If uninstall, not called from WordPress, then exit diff --git a/plugin-name/views/admin.php b/plugin-name/views/admin.php index 92dc429..865ed2b 100644 --- a/plugin-name/views/admin.php +++ b/plugin-name/views/admin.php @@ -5,11 +5,11 @@ * This includes the header, options, and other information that should provide * The User Interface to the end user. * - * @package PluginName - * @author TODO - * @license GPL-2.0+ - * @link TODO - * @since 1.0.0 + * @package PluginName + * @author Your Name + * @license GPL-2.0+ + * @link http://example.com + * @copyright 2013 Your Name or Company Name */ ?>
diff --git a/plugin-name/views/public.php b/plugin-name/views/public.php index a5be0e6..fdd4d80 100644 --- a/plugin-name/views/public.php +++ b/plugin-name/views/public.php @@ -5,13 +5,11 @@ * This typically includes any information, if any, that is rendered to the * frontend of the theme when the plugin is activated. * - * @package PluginName - * @subpackage views - * @author TODO - * @license GPL-2.0+ - * @link TODO - * @version 1.0.0 - * @since 1.0.0 + * @package PluginName + * @author Your Name + * @license GPL-2.0+ + * @link http://example.com + * @copyright 2013 Your Name or Company Name */ ?> \ No newline at end of file From 0ac81cc38f2018f792cf9811107d67d253d80f4d Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:44:58 -0400 Subject: [PATCH 7/9] adding notes for the new tag --- ChangeLog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 2a5d6c1..3e5654e 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,7 +1,7 @@ ## 2.5.0 (16 May 2013) -* Updated to `readme.txt` to be up to standard with the current WordPress Plugin Repository demo - +* Updating `readme.txt` to be up to standard with the current WordPress Plugin Repository demo +* Updating page-level DocBlocks for consistency ## 2.4.0 (15 May 2013) From e8c0c995982ac5c3283736d633643caca9fde6a4 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:56:20 -0400 Subject: [PATCH 8/9] updating the docblock in the class --- plugin-name/plugin-name.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugin-name/plugin-name.php b/plugin-name/plugin-name.php index bd93f8a..6f8db5a 100644 --- a/plugin-name/plugin-name.php +++ b/plugin-name/plugin-name.php @@ -8,7 +8,7 @@ * @package PluginName * @author Your Name * @license GPL-2.0+ - * @link example.com + * @link http://example.com * @copyright 2013 Your Name or Company Name * * @wordpress-plugin From e4d9af5304cd2184bb3691b60a8bfed0470111f0 Mon Sep 17 00:00:00 2001 From: Tom McFarlin Date: Thu, 16 May 2013 09:57:05 -0400 Subject: [PATCH 9/9] updating the docblock for this class --- plugin-name/class-plugin-name.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugin-name/class-plugin-name.php b/plugin-name/class-plugin-name.php index f78fe4c..8527190 100644 --- a/plugin-name/class-plugin-name.php +++ b/plugin-name/class-plugin-name.php @@ -5,7 +5,7 @@ * @package PluginName * @author Your Name * @license GPL-2.0+ - * @link example.com + * @link http://example.com * @copyright 2013 Your Name or Company Name */