Setting up a development environment

Wiki ▸ Documentation ▸ Developer Documentation ▸ Setting up a development environment

Better Angels' Buoy is written as a WordPress plugin. This guide may make more sense if you have at least some experience writing WordPress plugins, but should be easy to walk through for anyone comfortable using the command line.

The easiest way to get started contributing code is to use the Varying Vagrant Vagrants ("VVV") project to make a local WordPress development environment. Then fork the Buoy project on GitHub and git clone your fork into your VVV's wordpress-default/wp-content/plugins/ directory. The following instructions describe that process in more detail:

Your first Buoy dev install

1. Start with any local operating system such as Mac OS X, Linux, or Windows.
   • For Windows 8 or higher it is recommended that you run the cmd window as Administrator
2. Install git.
   • To check if git is already installed, use git --version to check the version.
3. Install VirtualBox 5.1.x
4. Install Vagrant 1.8.x
   • vagrant will now be available as a command in your terminal, try it out.
   • Note: If Vagrant is already installed, use vagrant -v to check the version. You may want to consider upgrading if a much older version is in use.
5. Optionally, install some convenient Vagrant plugins:
   1. Install the vagrant-hostsupdater plugin with vagrant plugin install vagrant-hostsupdater
      • Note: This step is not a requirement, though it does make the process of starting up a virtual machine nicer by automating the entries needed in your local machine's hosts file to access the provisioned VVV domains in your browser.
      • If you choose not to install this plugin, a manual entry should be added to your local hosts file that looks like this: 192.168.50.4 vvv.dev local.wordpress.dev local.wordpress-trunk.dev src.wordpress-develop.dev build.wordpress-develop.dev
   2. Install the vagrant-triggers plugin with vagrant plugin install vagrant-triggers
      • Note: This step is not a requirement. When installed, it allows for various scripts to fire when issuing commands such as vagrant halt and vagrant destroy.
      • By default, if vagrant-triggers is installed, a db_backup script will run on halt, suspend, and destroy that backs up each database to a dbname.sql file in the {vvv}/database/backups/ directory. These will then be imported automatically if starting from scratch. Custom scripts can be added to override this default behavior.
      • If vagrant-triggers is not installed, VVV will not provide automated database backups.
   3. Install the vagrant-vbguest plugin with vagrant plugin install vagrant-vbguest.
      • Note: This step is not a requirement. When installed, it keeps the VirtualBox Guest Additions kernel modules of your guest synchronized with the version of your host whenever you do vagrant up. This can prevent some subtle shared folder errors.
6. Clone or extract the Varying Vagrant Vagrants project into a local directory
   • git clone git://github.com/Varying-Vagrant-Vagrants/VVV.git vagrant-local
   • OR download and extract the repository master zip file to a vagrant-local directory on your computer.
   • OR download and extract a stable release zip file if you'd like some extra comfort.
7. In a command prompt, change into the new directory with cd vagrant-local
8. Start the Vagrant environment with vagrant up
   • Be patient as the magic happens. This could take a while on the first run as your local machine downloads the required files.
   • Watch as the script ends, as an administrator or su password may be required to properly modify the hosts file on your local machine.
9. Visit any of the following default sites in your browser:
   • http://local.wordpress.dev/ for WordPress stable
   • http://local.wordpress-trunk.dev/ for WordPress trunk
   • http://src.wordpress-develop.dev/ for trunk WordPress development files
   • http://build.wordpress-develop.dev/ for the version of those development files built with Grunt
   • http://vvv.dev/ for a default dashboard containing several useful tools
10. Create a GitHub account if you do not already have one.
11. Fork the Better Angels' Buoy project on GitHub to make a copy of the project in your own GitHub account.
12. In a command prompt, change into the default WordPress's plugins directory with cd www/wordpress-default/wp-content/plugins
13. Clone the Betters Angels' Buoy project into the WordPress plugins directory:
    • git clone https://github.com/YOUR_GITHUB_USER_NAME/buoy.git (replacing YOUR_GITHUB_USER_NAME with your GitHub account name)
14. Log in to your local default WordPress site in your browser: http://local.wordpress.dev/wp-login.php
    • Use the default admin user name: admin
    • Use the default admin password: password
15. Activate the Buoy plugin from the plugins screen: http://local.wordpress.dev/wp-admin/plugins.php

You are now running an instance of Buoy in an environment local to your development machine. Edit the files in vagrant-local/www/wordpress-default/wp-content/plugins/buoy/ to make changes to the code base. Then git add, git commit, and git push those files to your fork of the Buoy project as you are comfortable.

Finally, use a GitHub Pull Request to propose your changes for inclusion to the canonical Buoy repository for distribution to its official WordPress Plugin Repository.

Running tests

Buoy has partial unit test coverage under PHPUnit and Jasmine. The PHP tests are stored in the tests directory of the Buoy plugin and is ready to run out-of-the-box if you have followed the above Vagrant development environment setup. The JavaScript (Jasmine) tests are stored in its spec directory, and depend on Node.js, Bower, and Karma (aka. Testacular) to run.

To run the tests:

• PHPUnit:
  1. Log in to your development server with vagrant ssh
  2. Change into the Buoy plugin directory with cd /srv/www/wordpress-default/wp-content/plugins/buoy
  3. Run the tests with phpunit
• Jasmine:
  1. Download and install Node.js with the appropriate installer for your operating system. (Read this good beginner's guide if you are unfamiliar with Node.js's package manager, npm.)
  2. Install Bower with npm install -g bower (note that you may need to use sudo to install packages globally).
  3. Change into the Buoy plugin directory with cd vagrant-local/wordpress-default/wp-content/plugins/buoy
  4. Install the plugin's JavaScript dependencies with bower install
  5. Install the plugin's Node.js test runner dependencies with npm install
  6. Install the Karma test runner with npm install -g karma-cli (note that you may need to use sudo to install packages globally).
  7. Run the tests with karma start --single-run

Once you've completed setting up your development environment, you may have an idea of what code you want to edit. If not, look through Buoy's current issue queue and pick one of the issues to work on. Each change (pull request) to Buoy should ideally be paired with a unit test to ensure that the new code works and does not introduce problems to existing code.

Emails and txt messages in your development environment

Your development environment is a portable, self-contained WordPress and Buoy installation that is isolated from the rest of the Internet. Emails or SMS (txt) messages you send from code in your development environment are captured by a local instance of MailCatcher that comes pre-configured with VVV. To view outbound messages sent from your development environment, visit http://local.wordpress.dev:1080/ in your Web browser.

Generating documentation

Buoy's source code is fully commented using phpDocumentor-compatible docblocks. To generate the API documentation for Buoy:

1. Log in to your development server with vagrant ssh
2. Install PHP 5.6 and dependent modules if you have not already done so (because phpDocumentor is incompatible with PHP 7, still) with sudo apt-get install php5.6 php5.6-xml
3. Install phpdoc if you have not already done so:
   1. Become root with sudo su -, then:
   2. pear channel-discover pear.phpdoc.org
   3. pear install phpdoc/phpDocumentor
4. Change into the Buoy plugin directory with cd /srv/www/wordpress-default/wp-content/plugins/buoy
5. Generate the documentation with phpdoc (or php5.6 /usr/bin/phpdoc if your default PHP is version 7)

If you set up your environment as described above, developer documentation should now be available to you at http://local.wordpress.dev/wp-content/plugins/buoy/docs/

We also maintain a mirror of the developer documentation at https://betterangels.github.io/buoy/docs/

Multisite

Buoy can be run as a "Network Active" plugin across a WordPress Multisite network of sites. This gives each site in the network its own Buoy. This section explains how to set up a Multisite development environment using VVV's multisite configuration.

Automatic Multisite setup

Landfall is "an automated WordPress Multisite network deployment script for demoing the Buoy community-based crisis response system." It can be used to set up a Multisite development environmnet in one command line.

Manual Multisite setup

1. Complete the "Your first Buoy dev install" procedure described above.
2. Clone the vvv-multisite repository into your vagrant-local/www directory:
   • cd vagrant-local/www && git clone https://github.com/Varying-Vagrant-Vagrants/vvv-multisite.git
3. Re-provision your VVV install with vagrant reload --provision
4. Log into your development server with vagrant ssh
5. Create a symbolic link between the Buoy plugin's directory that you already created and the new WordPress Multisite installations:
   • Link the domain-based network install: ln -s /srv/www/wordpress-default/wp-content/plugins/buoy /srv/www/wpmu-subdomain/wp-content/plugins/buoy
   • Link the path-based network install: ln -s /srv/www/wordpress-default/wp-content/plugins/buoy /srv/www/wpmu-subdirectory/wp-content/plugins/buoy