Documenting VVV’s governance model

Earlier tonight I submitted a first draft of VVV’s governance model for comment by the community. This is one of those times as an open source software maintainer where you realize you’re doing something that should have been done a long time ago.

See also the time we added a license 1.5 years in 😅

As I started researching how one goes about documenting a governance model, I ran into “Planning for Sustainability“, from OSS Watch. At the bottom of that document are a few time estimates to help you project the level of effort in doing this all. They’ve marked 30 hours to “understand the different governance models” and create the document (from a template).

I kind of laughed at first, especially because VVV is not that big of a project. But here I am after 2 days of on and off research and documentation, probably somewhere about 6 hours in, thinking that they aren’t so far off.

It’s easier for VVV because it is (IMO) a fairly clear benevolent dictator model. I’ve led the project for 5 years and have relied on active members of the community for input throughout. I can imagine this being near impossible for larger projects where the project structure is less clear.

Of course, the benefit of spending so much time researching is parsing the great information that’s available thanks to years of others’ successful and failed attempts.

Here’s a walkthrough of some material I’ve found useful, along with commentary.

First, I’m happy to have run into the “Open-source governance” Wikipedia article early in the process. This does not directly describe governance for open source software, but instead the political philosophy of a community editable legislation. This helped set the tone in my head that my intent should be to document a clear explanation of how the project is managed rather than just a brief overview of my assumptions.

Next, all of the OSS Watch documentation was very useful. I spent some quality time with “Governance Models“, “Roles in Open Source Projects“, “Meritocratic Governance Model“, and “Benevolent Dictator Governance Model“. I almost used one of the provided templates, because it’s nicely open sourced as CC BY-SA 4.0, but decided to go completely custom.

I explored the models used by other other open source projects. In the process, I studied those from NodeJS, WP-CLI,  and Ubuntu among other random finds I stumbled on through GitHub’s search. This process taught me that not nearly enough open source projects provide a statement on governance. WP-CLI in particular inspired the inclusion of the project administration section so that clear documentation existed on server and domain management.

I also spent some time with some hard copies. The “Project Structures and Ownership” page from Homesteading the Noosphere was useful in wrapping my head around the word “benevolent dictator”, a term that I still don’t really like. And Producing Open Source Software is always so valuable. I went back again and again to “Benevolent Dictators“, “Social and Political Infrastructure“, “Choosing Committers“, and “Writing It All Down“.

My favorite phrase of the process comes from that last section:

living reflection of the group’s intentions, not a source of frustration and blockage

This sums the process up. A documented governance model is a document of intent, one that can be changed as the project matures, and it’s meant to provide a clear way for work to happen rather than a roadblock.

I’m looking forward to seeing what the community thinks!

Running PHPUnit on VVV from PHPStorm 9

I spent so much time trying to get this working last November and kept running into brick walls. Today, I finally revisited a comment on that same issue by Rouven Hurling that pointed out two excellent notes from Andrea Ercolino.

  1. How to run WordPress tests in VVV using PHPStorm 8
  2. How to run WordPress tests in VVV using WP-CLI and PHPStorm 8

These are both great examples of showing your work. Andrea walks through the issue and shows things that didn’t work in addition to things that did. I was able to use the first to quickly solve an issue that I’ve been so close to figuring out, but have missed every time.

And! I haven’t gone through the second article yet, but the hidden gem there is that he has remote debugging with Xdebug working while running tests with PHPUnit. I’ve wanted this so much before.

All that aside (go read those articles!), I stumbled a bit following the instructions and wanted to log some of the settings I had to configure in order for PHPUnit to work properly with PHPStorm 9 and my local configuration.

For this all to work, I had to configure 4 things. The first three are accessed via PHPStorm -> Preferences in OSX. The fourth is accessed via the Run -> Edit Configurations menu in OSX.

A remote PHP interpreter

Choosing “Vagrant” in the Interpreters configuration didn’t work for me. I got an error that VBoxManage wasn’t found in my path when I selected my Vagrant instance and it tried to auto-detect things. I’m not sure if this is a bug or a misconfiguration. I almost wonder if it’s related to my recent upgrade today to Vagrant 1.7.4 and VirtualBox 5.0.

Instead I tried going forward with “SSH Credentials” to see what would happen. I put in the IP of the VVV box, 192.168.50.4, and the vagrant/vagrant username and password combination for SSH. I left the interpreter path alone and when I clicked OK, everything was verified. I was hesitant, because in the first step I had already deviated from the plan.

PHPUnit configuration

This one was easier and didn’t require any altered steps. I added a remote PHPUnit configuration, chose the already configured remote interpreter and was good to close out.

SFTP deployment configuration

Because I was not able to get Vagrant configured properly in the first step, I am dealing with an entirely different path. PHPStorm wants to have a deployment configured over SFTP so that it can be aware of the path structure inside the virtual machine that leads to the tests.

Luckily nothing special needs to happen in the VM to support SFTP, so I was able to add 192.168.50.4 as the server and vagrant/vagrant as the username and password combination.

I originally tried putting the full path to WordPress here as the root directory, but that caused PHPStorm to prepend that on any automatic path building it did. I tried Autodetect as well, but that detected /home/vagrant, which did not work with the WordPress files. Through the power of deduction, I set the actual root / as the root. 😜

I also used the Mappings tab on this screen to match up my local wordpress-develop directory with the one I’m interacting with remotely.

Run/debug configurations

This one ends up being very straight forward now that everything else is configured. All I needed to do is select the phpunit.xml.dist file via its local path on my machine.

And then I was good! I can now run the single site unit tests  for WordPress core just by using the Run command via green arrows everywhere in PHPStorm.

The tests took 3.14 minutes to run through the interface versus 2.45 minutes through the command line, but I was given a bunch of information on skipped tests throughout. I’ll likely stick to the command line interface for normal testing, though I’m looking forward to getting Xdebug configured along side this as it will make troubleshooting individual tests for issues a lot easier.

Big thanks again to Andrea Ercolina for the great material that brought me to a working config!

Various Networking Configurations in VVV

I dug in to some different configurations in VVV today and decided to write them up as I went. This will be posted in some form to the VVV wiki as well. There are other networking configurations available in Vagrant, though I’m not sure that any would be useful in development with VVV.

I would recommend using default settings for initial provisioning as things can get quirky inside the VM when trying to access outside sources. Run vagrant reload to process any network configuration changes.

Private Network (default)

config.vm.network :private_network, ip: “192.168.50.4”

This is the default configuration provided in VVV. A private network is created by VirtualBox between your host machine and the guest machine. The guest is assigned an IP address of 192.168.50.4 and your host machine is able to access it on that IP. VVV is configured to provide access to several default domains on this IP address so that browser requests from your host machine just work.

Outside access from other devices to this IP address is not available as the network interface is private to your machine.

Port Forwarding

config.vm.network “forwarded_port”, guest: 80, host: 8080

One option to provide other devices access to your guest machine is port forwarding. Uncommenting or adding this line in VVV’s Vagrantfile and then running vagrant reload will cause any traffic on port 8080 directed at your host machine to instead communicate with port 80 on the guest machine.

This configuration will work with private or public IP configurations as it deals with port forwarding rather than the IP of the virtual machine itself.

An immediate way to test this once configured would be to type your host machine’s IP address into a browser followed by :8080. With port forwarding enabled, something like http://192.168.1.119:8080 would bring up the default VVV dashboard.

Of course, this doesn’t do you much good with the default WordPress sites, as you’ll be stuck adding port 8080 to every request you make.

The easiest hack around this is to setup port forwarding on your router. Point incoming requests for port 80 to port 8080 on the IP address of your host machine. Requests through the router will then traverse ports 80 (public IP) -> 8080 (host) -> 80 (guest) and your development work can be shared with devices inside and outside of your network.

Say my router’s public IP is 14.15.16.17 and my computer’s local IP is 192.168.1.100.

  • Enable port forwarding in Vagrantfile.
  • Configure router to forward incoming port 80 to port 8080 on 192.168.1.100.
  • Visit src.wordpress-develop.14.15.16.17.xip.io on my phone, connected through LTE.

There are other things you can do on your local machine to reroute traffic from 80 to 8080 so that it forwards properly without the use of a router. Sal Ferrallelo has posted steps to take advantage of port forwarding directly in OSX using pfctl.

Public Network

config.vm.network “public_network”

Replacing our default private network configuration with a public network configuration immediately provides access to other devices on your local network. Using this configuration without specifying an IP address causes the guest machine to request an address dynamically from an available DHCP server—likely your router. During vagrant up, an option may be presented to choose which interface should be bridged. I chose my AirPort interface as that is what my local machine is using.

==> default: Available bridged network interfaces:
1) en0: Wi-Fi (AirPort)
2) en1: Thunderbolt 1
3) p2p0
4) bridge0
5) vnic0
6) vnic1
    default: What interface should the network bridge to? 1

Once the guest machine receives an IP address, access is immediately available to other devices on the network.

  • vagrant ssh and type ifconfig to determine the IP address of the guest – mine was 192.168.1.141.
  • Visit src.wordpress-develop.192.168.1.141.xip.io on my phone, connected to the wireless network.

To me this is most desirable as it provides access to devices on the local network, not to the outside. If you are using public wifi or another insecure network, be aware–this does open your machine up to other devices on that network.

config.vm.network “public_network”, ip: “192.168.1.141”

The same configuration would be available without DHCP by specifying the IP address to use. If you know what subnet your network is on, this may be a shortcut for providing access without having to use ifconfig inside the guest machine.