Skip to content

Latest commit

 

History

History
312 lines (198 loc) · 11.1 KB

development-README.md

File metadata and controls

312 lines (198 loc) · 11.1 KB
Raw

README

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:

  1. ONLY fork and submit pull-requests to the master branch master!
  2. NEVER fork the production branches (below)!
  3. NEVER publish/release the master branch master anywhere!

PRODUCTION BRANCHES

Production branches are always supposed to be stable and can be released/published at any time.

M2 Pro (m2-pro)

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 (m2-free)

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)

DEVELOPMENT

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.

Implement version differences

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:

  1. Put the code into a product directory (prefered).
  2. Wrap code in product conditions.

Pull Requests

Always send pull requests to master branch unless a release is in QA. If a new version is already in QA, send your PR to development branch. We will merge these changes to master after releasing new version or QA is failed.

Product directories

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).

Product conditions

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 */

Working with the branches

Cloning

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

JS and CSS files

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.

Folder structure

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 and app/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"

AUTOMATION

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.

Grunt Task Runner

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.

Set up grunt

1. npm

First install node.js from: http://nodejs.org/

#!bash 
# Test it:
$ npm -v

# Install it system wide (optional but recommended):
$ npm install -g npm

2. grunt

Install grunt by running this command in command line:

#!bash 
# Install grunt:
$ npm install -g grunt-cli

3. Setup project

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

4. Install required tools

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>"

Set up wordpress-develop for unit tests

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

Unit testing notes

Introduction to unit testing in WordPress: http://codesymphony.co/writing-wordpress-plugin-unit-tests/

RELEASE

1. Build the release version

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.

Setting up the mixed repo in same folder (SVN + GIT)

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:

  1. Get a working copy of the GIT repo in local folder .../membership
  2. Get a working copy of the SVN repo in local folder .../membership-svn
  3. Now copy all files/folders (also hidden ones) from membership-svn into membership. Important: Only add/overwrite files. Do not delete the .git folder/files!!
  4. Verify in SVN that the membership folder now is a valid SVN repo. Now you can delete the poup-svn folder again.
  5. Now make sure that the .gitignore file contians the entry .svn
  6. 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!!

2. Update product versions

The example shows how to update the Pro-version, but the process for free version is identical.

  1. Switch to branch master
  2. Run grunt command $ grunt build:pro
  3. Switch to branch m2-pro
  4. Do a git pull, possibly some conflicts are identified!
  5. 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!

  1. Now commit and push the changes to bitbucket