Similar structure as: Membership 2, Popup, Custom Sidebars, CoursePress
The only development branch for M2 is master
. This branch ultimately is responsible for creating the production branches that are finally published.
Production branches are automatically built, based on the master branch. Any changes made to those other branches will be overwritten!
Remember: master
is the ONLY branch that should be edited and forked!
Notes:
- ONLY fork and submit pull-requests to the master branch
master
! - NEVER fork the production branches (below)!
- NEVER publish/release the master branch
master
anywhere!
Production branches are always supposed to be stable and can be released/published at any time.
M2 Pro is the official premium plugin that lives on WPMU DEV.
It uses libraries that are not included in the free version (like WPMU DEV Notification integration) and has all features.
M2 is the free limited version that gets published to the WordPress plugin directory.
It includes a special module to display up to 2 notifications to the user: Right after installation (sign up to a newsletter) and after seven days (rate plugin on wp.org)
As mentioned above: Only directly edit the branch master
. Other branches should be only updated via grunt tasks (see section "Automation" below).
Important: Do not let your IDE change the source order of the code. Fixing up formatting is fine, but moving code blocks around is not! It will confuse grunt and produce problems.
As mentioned, we will only update the master branch with all changes, even if those changes only relate to a specific product (like Premium version). There are two ways to add code that is specific to a single product only:
- Put the code into a product directory (prefered).
- Wrap code in product conditions.
The prefered way to implement different code is to move pro code into the subfolder /premium
. Code in the other directories is supposed to be core-plugin code (i.e. free plugin).
There are special comments in the master
branch will make sure some code only end up on the pro plugin and some code only end up in the free plugin.
Those are:
#!php
/* start:pro */
echo 'This is only in m2-pro';
/* end:pro */
/* start:free */
echo 'This is only in m2-free';
/* end:free */
M2 uses submodules, so use the --recursive
flag if you clone from command line:
#!bash
$ git clone [email protected]:incsub/membership-2.git --recursive
If you already have a cloned repo, you will need to init the submodule.
#!bash
$ git submodule init --
$ git submodule update
Only edit/create javascript and css files inside the /src
folders:
app/assets/js/src/*
for javascript.app/assets/css/src/*
for css. Use .scss extension (SASS)!
Important: Those folders are scanned and processed when running grunt. Files in base of app/assets/js/
and app/assets/css/
are overwritten by grunt.
Note:
There is a hardcoded list of js and scss files that are monitored and compiled by grunt. If you add a new js or scss file then you need to edit Gruntfile.js
and add the new file to the file list in js_files_concat
or css_files_compile
.
Plugin code:
app/
.. All code of the core (free version) goes here.app/assets/
.. contains all images, js, css (scss) and font files.
Special folders inside asset:
app/assets/js/src/
(source js-files)app/assets/css/src/
(source scss-files)Do not edit the .css and .js files in root of
app/assets/js
andapp/assets/css
, they are overwritten by grunt!
free/
.. contains the free version main membership.php file.premium/
.. All Premium-Only code belongs here!docs/
.. Public API documentation. Generated by grunt build.test/
.. contains PHP Unit Tests (run by grunt).
Files in these folders should not be modified directly:
lib/
.. External libraries and submodules.languages/
.. contains .pot translation files (generated by grunt, do not modify).node_modules/
.. files needed by grunt (see "Set up grunt" below).
Product folder premium
also contain the same subfolders as the core plugin app
folder.
Naming convention for files/folders:
- Prefix files that contian a php class with term "class-".
- Use lower-case only.
Example: "class-templatetag.php" not "class-templateTag.php"
- Use hyphen "-" instead of underscore "_".
Example: "class-core.php" not "class_core.php"
See notes below on how to correctly set up and use grunt.
Many tasks as well as basic quality control are done via grunt. Below is a list of supported tasks.
Important: Before making a pull-request to the master branch always run the task grunt
- this ensures that all .php, .js and .css files are validated and existing unit tests pass. If an problems are reported then fix those problems before submitting the pull request.
ALWAYS use Grunt to build the production branches. Use the following commands:
Category | Command | Action |
---|---|---|
Edit | grunt watch |
Watch js and scss files, auto process them when changed. Same as running grunt js and grunt css after each js/css change. |
Edit | grunt js |
Manually validate and minify js files. Do this after you merge changes or switch to a different branch. |
Edit | grunt css |
Manually validate and compile scss files to css. Same as js: After merge/switch branch. |
Test | grunt test |
Runs the unit tests. |
Build | grunt |
Run all default tasks: test, js, css. Run this task before submitting a pull-request. |
Build | grunt build |
Runs all default tasks + lang, builds all production versions. |
Build | grunt build:pro |
Same as build, but only build the pro plugin version. |
Build | grunt build:free |
Same as build, but only build the free plugin version. |
First install node.js from: http://nodejs.org/
#!bash
# Test it:
$ npm -v
# Install it system wide (optional but recommended):
$ npm install -g npm
Install grunt by running this command in command line:
#!bash
# Install grunt:
$ npm install -g grunt-cli
In command line switch to the membership
plugin folder. Run this command to set up grunt for the M2 plugin:
#!bash
# Install automation tools for M2:
$ cd <path-to-wordpress>/wp-content/plugins/membership
$ npm install
# Test it:
$ grunt hello
Same as 3: Run commands in the membership
plugin folder:
#!bash
$ cd <path-to-wordpress>/wp-content/plugins/membership
# Install composer:
$ php -r "readfile('https://getcomposer.org/installer');" > composer-setup.php
$ php composer-setup.php --filename=composer
$ php -r "unlink('composer-setup.php');"
# Install PHP Unit
$ php composer require --dev "phpunit/phpunit=4.8.*"
# Install PHP Code Sniffer:
$ php composer require --dev "squizlabs/php_codesniffer:2.*"
# Install WP Coding Standards:
$ git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git vendor/wpcs
$ vendor/bin/phpcs --config-set installed_paths ../../wpcs
# Config git with your Name/Email
$ git config user.email "<your email>"
$ git config user.name "<your name>"
If the command grunt test
fails you possibly need to follow these steps and install the wordpress-develop repository to your server.
The repository must exist at one of those directories:
/srv/www/wptest/wordpress-develop
/srv/www/wordpress-develop/trunk
- Or set the environment variable
WP_TESTS_DIR
to the directory
(See: tests/bootstrap.php line 12-21 for logic)
#!bash
# Create the directory at correct place:
$ mkdir /srv/www/wordpress-develop
# Download the WP-developer repository:
$ cd /srv/www/wordpress-develop
$ svn co http://develop.svn.wordpress.org/trunk/
# Run this to download latest WP updates:
$ cd /srv/www/wordpress-develop/trunk
$ svn up
Introduction to unit testing in WordPress: http://codesymphony.co/writing-wordpress-plugin-unit-tests/
1.) Switch to master
branch.
2.) Make sure the version number in main plugin file is correct and that the version in file pacakge.json
matches the plugin version. (in package.json you have x.y.z format, so "1.2.3.4" becomes "1.2.34" here)
3.) Then run grunt build
(or grunt build:pro
/ free). This will create a .zip archive of the release files and update the m2-pro
/-free
branches.
4.) Only in master
branch: There is a folder called release/
which contains the release files as .zip archive.
5.a) PRO: Simply upload the zip file from the release/
folder. The m2-pro
branch is not even needed.
5.b) FREE: (First set up a mixed repo as described below) After you built the free version, switch to the m2-free
branch and then commit those files to wp.org repository using SVN.
For wp.org releases I found the easiest solution is to have a "mixed" working copy, that contains both .git and .svn files. This way we only have one place where code is stored. Bitbucket is our main version control. SVN is only used/updated when a new version of the free version should be published.
This is the one-time setup routine I used to create this mixed working copy:
- Get a working copy of the GIT repo in local folder
.../membership
- Get a working copy of the SVN repo in local folder
.../membership-svn
- Now copy all files/folders (also hidden ones) from
membership-svn
intomembership
. Important: Only add/overwrite files. Do not delete the .git folder/files!! - Verify in SVN that the membership folder now is a valid SVN repo. Now you can delete the poup-svn folder again.
- Now make sure that the .gitignore file contians the entry
.svn
- When .gitignore is correct then revert all files in git to restore the master-branch. This will cause a lot of edits show up in SVN, but ignore those. The only time you want to use SVN is after you switched to the
membership-free
branch. ONLY THEN commit changes to SVN/wp.org!!
The example shows how to update the Pro-version, but the process for free version is identical.
- Switch to branch
master
- Run grunt command
$ grunt build:pro
- Switch to branch
m2-pro
- Do a git pull, possibly some conflicts are identified!
- Do NOT resolve the conflicts, but revert the conflicting files to last version!!
Grunt already committed the correct file version to git. The conflicts are irrelevant!
- Now commit and push the changes to bitbucket