GitHub | Chris Aldrich

Enabling two way communication with WordPress and GitHub for Issues

This week, using the magic of open web standards, I was able to write an issue post on my own website, automatically syndicate a copy of it to GitHub, and later automatically receive a reply to the copy on GitHub back to my original post as a comment there. This gives my personal website a means of doing two way communication with GitHub.

This functionality is another in a long line of content types my website is able to support so that I’m able to own my own content, yet still be able to interact with people on other websites and social media services. Given the number of social sites I’ve seen disappear over the years (often taking my content with them), this functionality gives me a tremendously larger amount of control and ownership over my web presence and identity while still allowing me to easily communicate with others.

In this post I wanted to briefly sketch what I’ve done to enable this functionality, so others who are so inclined can follow along to do the same thing.

Setting up WordPress to syndicate to GitHub

I’ll presume as a first step that one has both a GitHub account and a self-hosted WordPress website, though the details will also broadly apply to just about any content management system out there that supports the web standards mentioned.

Register your GitHub account and your website with Bridgy

Ryan Barrett runs a fantastic free open sourced service called Bridgy. To use it you’ll need the microformat rel=“me” links on both your GitHub account and your website’s homepage that point at each other. GitHub will do most of the work on its side for you simply by adding the URL of your website to the URL field for your GitHub account at https://github.com/settings/profile. Next on your website’s homepage, you’ll want to add a corresponding rel=“me” link from your website to your GitHub account.

In my case, I have a simple widget on my homepage with roughly the following link:
<a href="https://github.com/username">GitHub</a>
in which I’ve replaced ‘username’ with my own GitHub username. There are a variety of other ways to add a rel=“me” link to your webpage, some of which are documented on the IndieWeb wiki.

Now you can go to Brid.gy and under “Connect your accounts” click on the GitHub button. This will prompt you to sign into GitHub via oAuth if you’re not already logged into the site. If you are already signed in, Brid.gy will check that the rel=“me” links on both your site and your GitHub account reciprocally point at each other and allow you to begin using the service to pull replies to your posts on GitHub back to your website.

To allow Brid.gy to publish to GitHub on your behalf (via webmention, which we’ll set up shortly), click on the “Publish” button.

Install the Webmention Plugin

The underlying technology that allows the Bridgy service to both publish on one’s behalf as well as for the replies from GitHub to come back to one’s site is an open web standard known as Webmention. WordPress can quickly and easily support this standard with the simple Webmention plugin that can be downloaded and activated on one’s site without any additional configuration.

For replies coming back from GitHub to one’s site it’s also recommended that one also install and activate the Semantic Linkbacks Plugin which also doesn’t require any configuration. This plugin provides better integration and UI features in the comments section of one’s website.

Install Post Kinds Plugin

The Post Kinds Plugin is somewhat similar to WordPress’s Post Formats core functionality, it just goes the extra mile to support a broader array of post types with the appropriate meta data and semantic markup for interacting with Bridgy, other web parsers, and readers.

Download the plugin, activate it, and in the plugin’s settings page enable the “Issue” kind. For more details on using it, I’ve written about this plugin in relative detail in the past.

Install Bridgy Publish Plugin

One can just as easily install the Bridgy Publish Plugin for WordPress and activate it. This will add a meta box to one’s publishing dashboard that, after a quick configuration of which social media silos one wishes to support, will allow one to click a quick checkbox to automatically syndicate their posts.

Install the Syndication Links Plugin

The Syndication Links plugin is also a quick install and activate process. You can modify the settings to allow a variety of ways to display your syndication links (or not) on your website if you wish.

This plugin will provide the Bridgy Publish Plugin a place to indicate the permalink of where your syndicated content lives on GitHub. The Bridgy service will use this permalink to match up the original content on your website and the copy on GitHub so that when there are replies, it will know which post to send those replies to as comments which will then live on your own website.

Post away

You should now be ready to write your first issue on your website, cross post it to GitHub (a process known in IndieWeb parlance as POSSE), and receive any replies to your GitHub issue as comments back to your own website.

Create a new post.

In the “Kinds” meta box, choose the “Issue” option.

Screen capture of the Kinds meta box with "Issue" option chosen. — Kinds meta box with “Issue” option chosen.

Type in a title for the issue in the “Title” field.

In the “Response Properties” meta box, put the permalink URL of the Github repopository for which you’re creating an issue. The plugin should automatically process the URL and import the repository name and details.

In the primary editor, type up any details for the issue as you would on GitHub in their comment box. You can include a relatively wide variety of custom symbols and raw html including

and  with code samples which will cross-post and render properly.

In the GitHub meta box, select the GitHub option. You can optionally select other boxes if you’re also syndicating your content to other services as well. See the documentation for Bridgy and the plugin for how to do this.

Screen capture of the Bridgy Publish meta box with GitHub chosen — Bridgy Publish meta box with GitHub chosen.

Optionally set any additional metadata for your post (tags, categories, etc.) as necessary.

Publish your post.

On publication, your issue should be automatically filed to the issue queue of the appropriate GitHub repo and include a link back to your original (if selected). Your post should receive the syndicated permalink of the issue on GitHub and be displayed (depending on your settings) at the bottom of your post.

Syndication Links Plugin will display the location of your syndicated copies at the bottom of your post.

When Bridgy detects future interactions with the copy of your post on GitHub, it will copy them and send them to your original post as a webmention so that they can be displayed as comments there.

An example of a comment sent via webmention from GitHub via Brid.gy. It includes a permalink to the comment as well as a link to the GitHub user’s profile and their avatar.

If you frequently create issues on GitHub like this you might want a slightly faster way of posting. Toward that end, I’ve previously sketched out how to create browser bookmarklets that will allow you one click post creation from a particular GitHub repo to speed things along. Be sure to change the base URL of your website and include the correct bookmarklet type of “issue” in the code.

The Post Kinds plugin will also conveniently provide you with an archive of all your past Issue posts at the URL http://example.com/kind/issue/, where you can replace example.com with your own website. Adding feed/ to the end of that URL provides an RSS feed link as well. Post Kinds will also let you choose the “Reply” option instead of “Issue” to create and own your own replies to GitHub issues while still syndicating them in a similar manner and receive replies back.

Other options

Given the general set up of the variety of IndieWeb-based tools, there are a multitude of other ways one can also accomplish this workflow (both on WordPress as well as with an infinity of other CMSes). The outline I’ve provided here is one of the quickest methods for beginners that will allow a relatively high level of automation and almost no manual work.

One doesn’t necessarily need to use the Post Kinds Plugin, but could manually insert all the requisite HTML into their post editor to accomplish the post side of things via webmention. (One also has the option to manually syndicate the content to GitHub by cutting and pasting it as well.) If doing things manually this way is desired, then one will need to also manually provide a link to the syndicated post on GitHub into their original so that Bridgy can match up the copy and the original to send the replies via webmention.

More details on how to use Bridgy with Github manually in conjunction with WordPress or other CMSes can be found here: https://brid.gy/about#github-issue-comment

Further steps

If you’ve followed many of these broad steps, you’ve given already given yourself an incredibly strong IndieWeb-based WordPress installation. With a minimal amount of small modifications you can also use it to dovetail your website with other social services like Twitter, Facebook, Flickr, Instagram, Google+ and many others. Why not take a quick look around on the IndieWeb wiki to see what other magic you can perform with your website!

I’ve documented many of my experiments, including this one, in a collection of posts for reference.

Help

If you have questions or problems, feel free to comment below or via webmention using your own website. You can also find a broad array of help with these plugins, services, and many other pieces of IndieWeb technology in their online chat rooms.

Respond via Twitter:
Reply
Repost
Like

Add support for acquisition kind

Filed an Issue dshanske/indieweb-post-kinds (GitHub)

Adds support for responding to and interacting with other sites using the standards developed by the IndieWeb Community

Based on prior art and details in the IndieWeb Wiki for acquisitions.

I’m including some potential code below, though it will also require adding the appropriate icon and some meta data in a few places for the “Kinds” meta box as well as to the admin UI locations which are currently missing.

I’ve “cheated” a bit and defaulted to display the “wish” icon and thus some of its metadata, so the acquisition kind would need its own icon (the same shopping cart icon may be best) and some small meta data would need to be changed as well in the final.

For those who need to have this right away, the code below will “work” from a display standpoint.

Taxonomy Code template

Code snippet I’ve added to indieweb-post-kinds/includes/class-kind-taxonomy.php just under the section for the wish kind:

'acquisition'  => array(
    'singular_name'   => __( 'Acquisition', 'indieweb-post-kinds' ), // Name for one instance of the kind
    'name'            => __( 'Acquisitions', 'indieweb-post-kinds' ), // General name for the kind plural
    'verb'            => __( 'Acquired', 'indieweb-post-kinds' ), // The string for the verb or action (liked this)
    'property'        => 'acquired-of', // microformats 2 property
    'format'          => 'status', // Post Format that maps to this
    'description'     => __( 'Purchases, gifts, found things, or objects donated to me', 'indieweb-post-kinds' ),
    'description-url' => 'http://indieweb.org/acquisition',
    'show'            => true, // Show in Settings
    ),

Naturally the “true” flag for ‘show’ should be set to “false” until the code is feature complete.

A simple view for the acquisition post kind

Add the following code to the folder indieweb-post-kinds/views/ in a file named kind-acquisition.php

<?php
/*
 * Acquisition Template
 *
 */
$mf2_post = new MF2_Post( get_the_ID() );
$cite     = $mf2_post->fetch();
if ( ! $cite ) {
    return;
}
$author = Kind_View::get_hcard( ifset( $cite['author'] ) );
$url    = ifset( $cite['url'] );
$embed  = self::get_embed( $url );
?>

<section class="response h-product h-cite">

<header>

<?php
echo Kind_Taxonomy::get_before_kind( 'wish' );
if ( ! $embed ) {
    if ( ! array_key_exists( 'name', $cite ) ) {
        $cite['name'] = self::get_post_type_string( $url );
    }
    if ( isset( $url ) ) {
        echo sprintf( '<a href="%1s" class="p-name u-url">%2s', $url, $cite['name'] );
    } else {
        echo sprintf( '<span class="p-name">%1s</span>', $cite['name'] );
    }
    if ( $author ) {
        echo ' ' . __( 'by', 'indieweb-post-kinds' ) . ' ' . $author;
    }
    if ( array_key_exists( 'publication', $cite ) ) {
        echo sprintf( ' <em>(<span class="p-brand">%1s</span>)</em>', $cite['publication'] );
    }
}
?>

</header>

<?php
if ( $cite ) {
    if ( $embed ) {
        echo sprintf( '<blockquote class="e-summary">%1s', $embed );
    } elseif ( array_key_exists( 'summary', $cite ) ) {
        echo sprintf( '<blockquote class="e-summary">%1s</blockquote>', $cite['summary'] );
    }
}
// Close Response
?>

</section>

<?php

Future enhancements

Future additions/improvements to this kind could include potentially adding new data fields to indicate the “location purchased” as well as the “purchase price”, the “manufacturer” and maybe the “condition” with a dropdown for selecting options like brand new, like new, very good, good, acceptable, poor, and unspecified. These could be marked up with the h-product related microformats of p-price and p-brand. These would then need to be tucked into the view as appropriate as well.

GitHub goes IndieWeb

For a minute I thought that Github had gone all IndieWeb by changing color/branding to match that of the IndieWeb.org website and logos.

Then I realized that it was probably just a one day Halloween thing.

Alas… Happy Halloween IndieWebbers! 🎃

This has to be the most awesome Indieweb pull request I’ve seen this year.

This has to be the most awesome Indieweb pull request I've seen this year.

Heres why I did it: Trump

WithKnown is a fantastic, free, and opensource content management service that supports some of the most bleeding edge technology on the internet. I’ve been playing with it for over two years and love it!

And today, there’s another reason to love it even more…

This is also a great reminder that developers can have a lasting and useful impact on the world around them–even in the political arena.

My first pull request

Replied to My first pull request by

Clint Lalonde (ClintLalonde.net)

Crazy to think that, even though I have had a GitHub account for 5 years and have poked, played and forked things, I have never made a pull request and contributed something to another project unti…

Clint, first, congratulations on your first PR!

Oddly, I had seen the VERY same post/repo a few weeks back and meant to add a readme too! (You’ll notice I got too wrapped up in reading through the code and creating some usability issues after installing the plugin instead.)

Given that you’ve got your own domain and website (and playing in ed/tech like many of us are), and you’re syndicating your blog posts out to Medium for additional reach, I feel compelled to mention some interesting web tech and philosophy in the #IndieWeb movement. You can find some great resources and tools at their website.

In particular, you might take a look at their WordPress pages which includes some plugins and resources you’ll be sure to appreciate. One of their sets of resources is allowing you to not only syndicate your WP posts (what they call POSSE), but by using the new W3C webmention spec, you can connect many of your social media resources to brid.gy and have services like twitter, facebook, G+, instagram and others send the comments and likes on your posts there back to your blog directly, thereby allowing you to own all of your data (as well as the commentary that occurs elsewhere). I can see a lot of use for education in some of the infrastructure they’re building and aggregating there. (If you’re familiar with Known, they bake a lot of Indieweb goodness into their system from the start, but there’s no reason you shouldn’t have it for your WordPress site as well.)

If you need any help/guidance in following/installing anything there, I’m happy to help.

Congratulations again. Keep on pullin’!

Ten Simple Rules for Taking Advantage of Git and GitHub

Bookmarked Ten Simple Rules for Taking Advantage of Git and GitHub (journals.plos.org)

Bioinformatics is a broad discipline in which one common denominator is the need to produce and/or use software that can be applied to biological data in different contexts. To enable and ensure the replicability and traceability of scientific claims, it is essential that the scientific publication, the corresponding datasets, and the data analysis are made publicly available [1,2]. All software used for the analysis should be either carefully documented (e.g., for commercial software) or, better yet, openly shared and directly accessible to others [3,4]. The rise of openly available software and source code alongside concomitant collaborative development is facilitated by the existence of several code repository services such as SourceForge, Bitbucket, GitLab, and GitHub, among others. These resources are also essential for collaborative software projects because they enable the organization and sharing of programming tasks between different remote contributors. Here, we introduce the main features of GitHub, a popular web-based platform that offers a free and integrated environment for hosting the source code, documentation, and project-related web content for open-source projects. GitHub also offers paid plans for private repositories (see Box 1) for individuals and businesses as well as free plans including private repositories for research and educational use.

Git and Version Control for Novelists, Screenwriters, Academics, and the General Public

Marginalia and Revision Control

At the end of April, I read an article entitled “In the Margins” in the Johns Hopkins University Arts & Sciences magazine. I was particularly struck by the comments of eminent scholar Jacques Neefs on page thirteen (or paragraph 20) about computers making marginalia a thing of the past:

Neefs believes contemporary literature is losing a valuable component in an age when technology often precludes and trumps the need to save manuscripts or rough drafts. But it is not something that keeps him up at night. ‘The modern technique of computers and everything makes [marginalia] a thing of the past,’ he says. ‘There’s a new way of creation. Some would say it’s tragic, but something new has been invented. I don’t consider it tragic. There are still great writers who write and continue to have a way to keep the process.’

Photo looking over the shoulder of Jacques Neefs onto the paper he's been studing on the table in front of him. — Jacques Neefs (Image courtesy of Johns Hopkins University)

I actually think that he may be completely wrong and that current technology actually allows us to keep far more marginalia! (Has anyone heard of digital exhaust?) The bigger issue may be that many writers just don’t know how to keep a better running log of their work to maintain all the relevant marginalia they’re actually producing. (Of course there’s also the subsequent broader librarian’s “digital dilemma” of maintaining formats for the future. As an example, thing about how easy or hard it might be for you to read that ubiquitous 3.5 inch floppy disk you used in 1995.)

A a technologist who has spent many years in the entertainment industry, I feel compelled to point everyone towards the concept of revision control (or version control) within the realm of computer science. Though it’s primarily used in tracking changes in computer programs and is often a tool used by large teams of programmers, it can very easily be used for tracking changes in almost any type of writing from novels, short stories, screenplays, legal contracts, or any type of textual documentation of nearly any sort.

Example Use Cases for Revision Control

Publishing

As a direct example, I’m using what is known as a Git repository to track every change I make in a textbook I’m currently writing. I can literally go back and view every change I’ve made since beginning the project, so though I’m directly revising one (or more) text files, all of my “marginalia” and revisions are saved and available. Currently I’m only doing it for my own reference and for additional backup not supposing that anyone other than myself or an editor possibly may want to ever peruse it. If I was working in conjunction with otheres, there are ways for me to track the changes, edits, or notes that others (perhaps an editor or collaborator) might make.

In addition to the general back-up of the project (in case of catastrophic computer failure), I also have the ability to go back and find that paragraph (or multiple pages) I deleted last week in haste, but realize that I desperately want them back now instead of having to recreate them de n0vo.

Because it’s all digital, future scholars also won’t have problems parsing my handwriting issues as has occasionally come up in differentiating Mary Shelley’s writing from that of her husband in digital projects like the Shelley Godwin Archive. The fact that all changes are tracked and placed in a tree-like structure will indicate who wrote what and when and will indicate which changes were ultimately accepted and merged into the final version.

Screenplays in Hollywood

One particular use case I can easily see for such technology is tracking changes in screenplays over time. I’m honestly shocked that every production company or even more likely studios don’t use such technology to follow changes in drafts over time. In the end, doing such tracking will certainly make Writers Guild of America (WGA) arbitrations much easier as literally every contribution to a script can be tracked to give screenwriters appropriate credit. The end results with the easy ability to time-machine one’s way back into older drafts is truly lovely, and the outputs give so much more information about changes in the script compared to the traditional and all-too-simple (*) which screenwriters use to indicate that something/anything changed on a specific line or the different colored pages which are used on scripts during production.

I can also picture future screenwriters using services like GitHub as platforms for storing and distributing their screenplays to potential agents, managers, and producers.

Redlining Legal Documents

Having seen thousands of legal agreements go back and forth over the years, revision control is a natural tool for tracking the redlining and changes of legal documents as they change over time before they are finally (or even never) executed. I have to imagine that being able to abstract out the appropriate metadata in the long run may actually help attorneys, agents, etc. to become better negotiators, but something like this is a project for another day.

Academia

In addition to direct research for projects being undertaken by academics like Neefs, academics should look into using revision control in their own daily work and writings. While writing a book, paper, journal article, essay, monograph, etc. (or graduate students writing theses) one could use their own Git repository to not only save but to back up all of their own work not only for themselves primarily, but also future scholars who come later who would not otherwise have access to the “marginalia” one creates while manufacturing their written thoughts in digital form.

I can easily picture Git as a very simple “next step” in furthering the concept of the digital humanities as well as in helping to bridge the gap between C.P. Snow’s “two cultures.” (I’d also suggest that revision control is a relatively simple step one could take before learning a particular programming language, which I think should be a mandatory tool in everyone’s daily toolbox regardless of their field(s) of interest.)

Start Using Revision Control

“But how do I get started?” you ask.

Know going in that it may take parts of a day to get things set up and running, but once you’ve started with the basics, things are actually pretty easy and you can continue to learn the more advanced subtleties as you progress. Once things are working smoothly, the additional overhead you’ll be expending won’t be too much more than the old method of hitting Alt-S to save one of your old Word documents in the time before auto-save became ubiquitous.

First one should start by choosing one of the myriad revision control systems that exist. For the sake of brevity in this short introductory post, I’ll simply suggest that users take a very close look at Git because of its ubiquity and popularity in the computer science world and the fact that it includes a tremendously large amount of free information and support from a variety of sites on the internet. Git also has the benefit of having versions for all major operating systems (Windows, MacOS, and Linux). Git also has the benefit of a relatively long and robust life within the computer science community meaning that it’s very stable and has many more resources for the uninitiated to draw upon.

Once one has Git installed on their computer and has begun using it, I’d then recommending linking one’s local copy of the repository to a cloud storage solution like either GitHub or BitBucket. While GitHub is certainly one of the most popular Git-related services out there (because it acts, in part, as the hub for a large portion of the open internet and thus promotes sharing), I often recommend using BitBucket as it allows free unlimited private but still share-able repositories while GitHub requires a small subscription fee for keeping one’s work private. Having a repository in the cloud will help tremendously in that your work will be available and downloadable from almost anywhere and because it also serves as a de-facto back-up solution for your work.

I’ve recently been playing around with version control to help streamline the writing/editing process for a book I’ve been writing. Though Git and it’s variants probably seem more daunting than they should to the everyday user, they really represent a very powerful tool. I’ve spent less than two days learning the basics of both Git and hosted repositories (GitHub and Bitbucket), and it has been more than well worth the minor effort.

There is a huge wealth of information on revision control in general and on installing and using Git available on the internet, including full textbooks. For the complete beginners, I’d recommend starting with The Chronicle’s “A Gentle Introduction to Version Control.” Keep in mind that though some of these resources look highly technical, it’s because many are trying to enumerate every function one could potentially desire, when even just the basic core functionality is more than enough to begin with. (I could analogize it to learning to drive a car versus actually reading the full manual so that you know how to take the engine apart and put it back together from scratch. To start with revision control, you only need to learn to “drive.”) Professors might also avail themselves of the use of their local institutional libraries which may host small sessions on learning such tools, or they might avail themselves of the help of their colleagues or students in the computer science department. For others, I’d recommend taking a look at Git’s primary website. BitBucket has an excellent step-by-step tutorial (and troubleshooting) for setting up the requisite software and using it.

What do you use for revision control?

I’ll welcome any thoughts, experiences, or additional resources one might want to share with others in the comments.