Posted on

Bitbucket Major Outtage

Bitbucket, an online code management and issue tracking system, used for the Store Locator Plus projects, is currently offline due to what is classified as a “Major Outage”.   Development and patches for the Store Locator Plus products is limited as I wait for the service to come back online.    While development can continue, the longer the service is out the higher the risk of losing local code edits should the development system encounter problems.   The remote code management system not only provides controlled and documented software change control but also serves as a type of “immediate off-site backup” should anything go wrong.   While I do run routine backups of all systems here at CSA, those backups are not very granular, meaning I may have a snapshot from 4 hours ago but not from 4 minutes ago.   4 hours can be a LOT of lines of code written.

Site content, documentation, and non-code related projects will be underway as I await the return of the Bitbucket service.     With two major outages in a month it may warrant considering a change of service providers which is time consuming and disruptive.    Github, while somewhat more stable is not without its problems and gets costly in a hurry for larger projects like Store Locator Plus.   Repository Hosting gets decent reviews.  May be time to investigate, but I am not looking forward to moving hundreds of logged issues and enhancements.

This is one of the downsides to using third party services.  If you are not fully self-sufficient, and few online service are these days, you are vulnerable to the whims and follies of your vendors.  Sadly many online vendors these days have limited, if any, transparency into their operations.

That is one of the advantages to buy-and-own-it open source projects like Store Locator Plus.    If I go away you still have fully functional code that is readily accessible to your and your development team which limits your potential down time and exposure.    As the Store Locator Plus community builds more developers are getting involved which bolsters the potential longevity of the plugin.   While some people are apprehensive about open source projects I find it is typically from businesses that write applications and are looking to protect their profitability.   For the consumer I have yet to hear a compelling argument as to why well-written open source software is a detriment.

Posted on

Making GitHub Wiki Docs From PHP Source

I’ve been using NetBeans to write my PHP-based WordPress plugins and have found that well crafted PHPDoc comments make a notable difference in the efficiency of my coding.   I’ve written a post-or-two about that and find the auto-fill features to be very helpful.    I have also noticed that much of the WordPress core also follows PHPDoc conventions, so using PHPDoc is a good way to comment your WordPress plugin code IMO.

The other tools I use frequently are GitHub with SmartGit.   While git had a steeper learning curve than subversion, I much prefer the lighter “differential data” standard of git as well as the distributed repository concept.   Both just “feel” smarter.   The next logical step from tracking code commits and issues with GitHub was finding a home for my code documentation.     I really didn’t want to manually great web pages from the PHDoc raw HTML.  I also didn’t want to write a plugin to read PHPDoc to get the content into my website, so I went on a quest to find the tools needed to publish my PHP comments right on the GitHub wiki pages.    After a long search I finally found the pieces of the puzzle I needed to go from PHP comments to GitHub wiki pages with limited effort.  The process is outlined below.

Clone Your GitHub Wiki Pages

  • Go to your GitHub project and look for the Wiki tab. If you do not have it, especially for an older project, you may need to enable “pages” in the repo settings at GitHub.
  • Under the Wiki tab is a sub-tab for “Git Access”. It has the WIKI repo URL, which will automatically be attached to the parent project under the wiki tab.
  • Clone this to a new directory on your dev box.
  • (BTW, this step is optional, this is just how I opted to do this, keep the docs OUT of my main code repo).

Setup/Build The PHPDocMD Tool

$docmdDir = dirname(<strong>FILE</strong>);
// Potential composer autoloader paths $paths = array( $docmdDir . '/../src/PHPDocMD/Parser.php', $docmdDir . '/../src/PHPDocMD/Generator.php', $docmdDir . '/../src/Twig/lib/Twig/Autoloader.php', );
foreach($paths as $path) { if (file_exists($path)) { include $path; print "including $path\n"; } }
// Everts crappy option parser.

These code edits are necessary because the tool is not refined yet. It was clearly setup for the developer’s system which has Twig installed and a vendor autoloader file that is not in the git repo. Not a big deal, easy enough to get around if you follow the steps here.

BTW, that last comment is his, not mine. I left if there so you know where to stop the edit.

Use PhpDoc & PHPDocMD

You may want to symlink that phpdocmd to your /usr/bin directory so you don’t have to type the full path every time, but now you just need a few steps to create GitHub Wiki compatible doc files:

# phpdoc -t . -d .

That creates the structure.xml file needed to generate the MD files.

Then run this command:

# phpdocmd ./structure.xml <path to your github WIKI project>

Now your GitHub Wiki Docs project should be full of MD files that reflect your code PHPDocs. Just push your GitHub Wiki files back to the GitHub server.

Posted on

SmartGit Tips & Tricks

I have been using SmartGit ( for nearly a year now.   After having used command-line git and the graphical log viewer, gitk, I have become very accustomed to using SmartGit for managing my code repositories.   After a short learning curve I have become fairly proficient in managing my branches and general code repository issues.

Here are some tips & tricks I’ve learned along the way.  Granted, not many listed here yet, but hopefully other SmartGit users out there will share.

Tagging Code

Tags are very useful for marking key positions in the repository without creating a branch.   We use this at Cyber Sprocket to tag the commit that represents a specific product release.    SmartGit makes this easy, but you will need to create a private key.   Look for our articles on creating OpenSSH keys using PuttyGen to create your key file.

Once you have your key file you can attach it to a project when you set the project up.  SmartGit will store that key for future use, making for easy tagging of your repository.

At this point tagging the repository is easy:

  • Open the log viewer.
  • Right-click on a commit and select “Add Tag”.
  • To publish the tag back to the origin server go to the working tree/project window and select “remote / push advanced” and select the “push selected branches or tags”.  That is where you can select the new tag and push it back to origin.

Finding A Commit By ID

Even though SmartGit is very good at managing branches and encouraging plain text labels for branches and tags, there are times when the only way you can find a specific commit is via the SHA-1 commit ID.    For months I’d been using the command line to locate those commits and manage them, often just to add a tag or a branch so I could find that key commit at a later date.

Turns out SmartGit has an easy, if somewhat hidden, way to find a commit.

  • Bring up the log window.
  • Start typing in the SHA-1 key -or- press ctrl-v to paste in a hash you’ve copied

SmartGit will locate the first matching commit ID doing the typical fast search/filter as you continue typing.


Those are my two tips & tricks for today.  If you have any, please share.