Thinking through Git in my work

This is mostly me thinking through some issues.

I use git and GitHub a fair amount. Not enough, not deeply enough, but a fair amount.

I understand Use Case #1, Compiled App, like RLangSyntax:

• code in ~/dev/Project
• subdirs (test/, lib/, examples/, docs/, etc) and documentation, license and build scripts in to git
• git push origin master
• compile code to binary, deploy the binary elsewhere (like GitHub's releases tab)

When someone wants to use this code, git clone Project gets you all you need to build it, except for compilers and associated libraries, which should be in README.md. (I forgot to put how to build into the RLangSyntax docs, then forgot how to build RLangSyntax. Forgive me, Admin, for I have sinned.)

Let's jump to Use Case #2, Perl Library, like Spark.pm.

• code in ~/dev/Project
• no build instructions; it's built
• tests in ~/dev/Project/t/spark.t and the like (which this doesn't have, to my shame)
• git push origin master

This is where I get confused. Eventually, this code needs to be in /production/lib, but you don't want to deploy using git pull or git clone, because you don't want /production/lib/Project/. Or, maybe you do and I just don't get it. Still, this is a case that I can do an acceptably wrong thing as required.

Use Case #3 is Perl command-line tools. We'll take on my twitter tool.

• code in ~/dev/project
• git push origin master

This begs about the same question as Perl Library. It could work to have ~production/bin/twitter.pl/twitter.pl, but then you have to expand your path to include every little thing. It gets more involved if you have libraries with executables in the repo, or the reverse, but let's get to the real hairball.

Use Case #4, the Hairball, is our web stuff.

• ~web/ - document root
• ~web/data - holds data that we want to make web-accessable
• ~web/images - images for page headers and other universal things
• ~web/lib - all our JavaScript
• ~web/css - all our Cascading Style Sheets
• ~web/cgi-bin - our server-side code

So, we might have the server-side code in ~web/cgi-bin/service/Project/foo.cgi, the client-side code in ~web/lib/Project/foo.js but maybe in ~web/lib/foo.js, the style in ~web/css/project.css and ~/web/css/service.css, and of course the libraries in ~production/lib/.

Maybe the key is to think of the ~web/lib and ~web/css as variations of Use Case #2, but the problem is that a lot of my JS code isn't general like the Perl code. I mean, wherever you want a sparkline, you can use Spark.pm, but the client code for ~/cgi-bin/service/Project/foo.cgi is going to mostly be very specific to foo.cgi except for the jQuery, Mustache and a few other things that are in use across services and projects.

A possible solution, having things be in ~web/service, with the JSON APIs in ~web/cgi-bin/service/apis and the JavaScript in either ~web/service/lib or ~/web/lib depending on how universal it is, but we lose certain abilities. I certainly have written CGI code which mostly puts out as little HTML as it needs to get the JS, which works for the small audience those tools need.

I mostly code foo.js in relation to foo.cgi or foo.html, but making tests and breaking it into pieces may keep me from having KLOC-size libraries I hate to work on in the future.

And here, we have departed from git into project and web architecture, and into best practices. Still, any suggestions would be gladly accepted.

A little bit on OAuth and Net::Twitter on the Command Line

I have a Twitter application up on Github. I quote:

#!/usr/bin/perl

# largely taken verbatim from
# http://search.cpan.org/dist/Net-Twitter/lib/Net/Twitter/Role/OAuth.pm

# Next step is to get the keys and secrets to a config.

# you need to get your own access token and secret (which identifies you
# as a developer or application) and consumer key and secret (which
# identifies you as a Twitter user). You cannot use mine.

use 5.010 ;
use strict ;
use IO::Interactive qw{ interactive } ;
use Net::Twitter ;
use Carp ;

my $status = join ' ', @ARGV ;
if ( length $status < 1 ) {
    while ( <stdin> ) {
        $status .= $_ ;
        }
    chomp $status ;
    }

if ( length $status > 140 ) {
    say { interactive } 'Too long' ;
    say { interactive } length $status ;
    exit ;
    }
if ( length $status < 1 ) {
    say { interactive } 'No content' ;
    say { interactive } length $status ;
    exit ;
    }

say $status ;

# GET key and secret from http://twitter.com/apps
my $twit = Net::Twitter->new(
        traits          => [ 'API::REST', 'OAuth' ],
        consumer_key    => 'consumer_key' ,   #GET YOUR OWN
        consumer_secret => 'consumer_secret', #GET YOUR OWN
        ) ;

# You'll save the token and secret in cookie, config file or session database
my ( $access_token, $access_token_secret ) ;
( $access_token, $access_token_secret ) = restore_tokens() ;

if ( $access_token && $access_token_secret ) {
    $twit->access_token( $access_token ) ;
    $twit->access_token_secret( $access_token_secret ) ;
    }

unless ( $twit->authorized ) {

    # You have no auth token
    # go to the auth website.
    # they'll ask you if you wanna do this, then give you a PIN
    # input it here and it'll register you.
    # then save your token vals.

    say "Authorize this app at ", $twit->get_authorization_url, ' and enter the PIN#' ;
    my $pin = <stdin> ;    # wait for input
    chomp $pin ;
    my ( $access_token, $access_token_secret, $user_id, $screen_name ) =
      $twit->request_access_token( verifier => $pin ) ;
    save_tokens( $access_token, $access_token_secret ) ;    # if necessary
    }

if ( $twit->update( $status ) ) {
    say { interactive } 'OK' ;
    }
else {
    say { interactive } 'FAIL' ;
    }

#========= ========= ========= ========= ========= ========= =========

# Docs-suggested
sub restore_tokens {
    my $access_token = 'token' ;            #GET YOUR OWN
    my $access_token_secret = 'secret' ;    #GET YOUR OWN
    return $access_token, $access_token_secret ;
    }

sub save_tokens {
    my ( $access_token, $access_token_secret ) = @_ ;
    say 'access_token: ' . $access_token ;
    say 'access_token_secret: ' . $access_token_secret ;
    return 1 ;
    }

I mention this, in part, because I'm going back to the code so I can automate tweets for @PurduePM, the Twitter feed of the Purdue Perl Mongers, which I am taking over.

I remember that, when I wrote this and first tried to use it, it frustrated and confused me. When I tried to dust it off this afternoon, I found it to be downright easy. I wiped the access tokens and ran the code. It hit the if statement, gave you the authentication URL and waited for a PIN. Given that, it "saved" the tokens (by which I mean "wrote to STDOUT". I then put the access token and speed. The means I have for saving and restoring tokens, which is less than minimal, could easily be improved. Thing is, I have no means within the code to distinguish between users. The usage is twitter.pl This is a tweet or echo This is another tweet | twitter.pl, with the entirety of @ARGV being concatenated into the message, so it's entirely within the code whether we're determining which account is being used.

But, it strikes me I could make aliases. Alias twitter to "twitter.pl jacobydave " and shift the username from @ARGV. (BTW, I'm on Twitter as @JacobyDave. Follow me.) Then, alias twit_ppm or something to "twitter.pl purduepm " and so on.

I really got to the "it works, so can I please get to the next thing?" stage and stopped playing with it, before I got to the really interesting point. I'm certainly beginning to appreciate how useful and cool OAuth is. I'll attempt to come up with the next better thing, as well as put together the means to store the keys in an external file. Remember, you'll have to get to the Twitter Developer page and create an app to get the crucial consumer key if you want to use this code. If I let you have mine, and someone starts using it to spam a lot, Twitter might revoke the key to protect itself. 

Book Review - Version Control by Example, or "Thank you, @eric_sink"

For too long, I've worked in environments without version control. There's been backups, either real or virtual, and for the web part there's the Google cache (which saved by butt once as the webmaster for my LUG) but version control has always been something that I know I should be doing, but we've never done. (The one exception was doing temp work at the car parts company. There, we used code reviews and Synergy. Not the good Synergy, which gives you the ability use one keyboard and mouse across several computers in software, but the bad one, the ancient, slow and ponderous configuration management system, which is similar enough to version control that I cannot express the distinction.

So, here's something where I know I should be doing it, but I don't really know how to do it. I've heard enough about Git and have signed up with Github, which put it before Subversion and CVS and the rest of the choices. But, unfortunately, I hadn't heard enough about Git to really know what the heck I should be doing with it.

Then I saw a post by my internet friend Funnel Fiasco about Version Control by Example by Eric Sink, saying how good it was. And, as it turns out, Eric is much more about teaching people about how to not do stupid things than he is about sales, so you can download digital copies, browse through online, and he'll even send you a copy free.

I've had it in my bag for several months without cracking it open, which was stupid of me. Right now, I'm in a decent place at work, with little sitting with a tight deadline, so I have time to go through the book and start  actually learning from it, and wow! I'm getting it! It makes sense. The core of the book is the same examples expressed in Subversion, Mercurial, Veracity and Git, so it serves as a Rosetta Stone, too, so if you know one, you have a step toward using the others if that's what your workplace or project uses.

Thank you, Eric Sink!

Speaking of git

mount.pl, my script for automating the mounting and unmounting of remote file systems via sshfs, is now on github.