Github Pages

I have for long wanted to do something with Github Pages. I have seen cool projects having great websites for promotion and acting as landing pages and frontpages to Github repositories and the integration just seems to come so easy, but I could not really find the time to have a crack at it.

Then I read a Github blog post stating “Publishing with GitHub Pages, now as easy as 1, 2, 3”, so I think, well know it must be about time.

I have had a plan to do some promotion of the repository and Perl distribution Workflow. But I wanted to do some experimenting first, to get a feel for the process, tweaks and tricks and the result.

I started with my personal Github page, then that and my Today I Learned repository. Utilizing the available themes was quite easy, but that would mean that your site/page at some point look like everybody else’s and the point of doing promotion is to stand out.

I have several Perl distributions on Github, I would for them to have some sort of resemblance so they would be easily identifiable as homepages for Perl distributions. MetaCPAN can utilize a link to a homepage using CPAN Metadata (See the specification: CPAN::Meta::Spec, resources).

homepage.png

Getting this set using Dist::Zilla was described in my latest blog post.

Well I decided for the Cayman theme and I decided to go for some basic customisation.

Github Pages uses Jekyll and adding a theme is quite easy doing it via the Github repository settings.

settings.png

I am a complete n00b at this Jekyll stuff and I am primarily programming and not doing layout using CSS and HTML – I am one of those programmers who love Bootstrap. But I successfully got Jekyll running locally.

Anyway I forked Cayman repository and got it working so I could do changes, tweaks and customization.

When I finally got the “Cayman” theme to look like what I wanted, I ported my changes to me repository using the Cayman theme following this piece of documentation.

The actual porting is quite simple, but I had to translate from some Sass directives to pure CSS. This was done using a combination of inspecting elements using the browser and copy-pasting CSS directive from my fork of the Cayman theme.

Lifted from the documentation referenced above:

custom.png

My final result got to look as follows:

---
---

@import "{{ site.theme }}";

.page-header {
  color: #fff;
  text-align: center;
  background-color: #fff;
  background-image: linear-gradient(to bottom, #1e6bb8, #fff);
}

.main-content {
    h1, h2, h3, h4, h5, h6 {
        margin-top: 2rem;
        margin-bottom: 1rem;
        font-weight: normal;
        color: #222;
    }
}

And you can see the result here: https://jonasbn.github.io/perl-test-timer/

Apart from getting to learn a bit about Jekyll, Sass, I learned a bit about CSS3 gradients. I know my customizations are in the low end, but as I stated I would love to do something, which could communicated that it was a Perl 5 distribution, but the Perl 5 brand is somewhat vague – so the next step is to spark some creativity to take this new customizations to a new level and if it is going to be widely used for my distributions, perhaps be folded into some sort of standardised theme, which can be easily applied to several repositories.

If you want to help me create a Perl Jekyll Github Page Theme – ideas and suggestions are most welcome…

 

Github Pages

Public Specifications FTW

Please note that this post is by no means endorsed by my employer, it is a personal reflection on a strategic move I have participated in, in my line of work as a professional software developer.

The above paragraph, which I felt I a need to write as a part of this blog post, is very aligned with the actual post topic in itself, please read on.

The place where I work have for a long time published specifications on some of the offered services. Either this was done using our CMS or using PDF artefacts from a Wordprocessor.

Both processes where tedious and held several issues:

  • Content in CMS
    1. Hard to edit longer documents with figures and cross references
    2. Version control was not obvious
    3. Drafts compared to published documents was not used
  • Wordprocesser artefacts
    1. Version control practically non-existing or external
    2. Document control based on files shares, folders and naming conventions
    3. Manual publication proces

There was probably several other issues I have happily forgotten, like PDF meta-data removal etc.

After having done a lot of open source work in Markdown and on Github and in conjunction with releases of some open source demo clients for our services, I proposed that we published the accompanying public specifications on Github.

This proved to be a very clever move.

It did require some consideration on our side and it was quite a new move to us. Yes we had published specifications for public availability for long a time, but putting these in a public repository was still a new move for us. But the concerns hastily evaporated and the proces became natural and incredibly productive compared to the old processes.

At the time of writing we have 6 open sourced specifications and 3 clients accompanying these and a repository with XSD files supplementing one of the specifications.

Not all of the specifications are finished, but they are out there, so if somebody wants to see what is going on, they are most welcome. We have only received a single pull-request and that is completely okay. We do not want somebody to write our specifications, that is our job, but corrections to sample code, clarifications and of course spelling corrections are most welcome.

Here are some of the pros I have observed:

  • Using Git and Markdown
    1. Version control is built-in
    2. Markdown is quite powerful and easy to edit
    3. Syntax highlighting of code samples (bash, XML, JSON, text etc.)
    4. The flow resembles a development flow and the toolchain is somewhat the same
    5. Tagging of versions and complete history is available
    6. An engaging proces supporting pull-requests (oh well)
    7. Branching for new editions and proposals for change requests

Currently one of the specification has 4 branches, when evaluation and review is finalized, will be merged onto the master, which can be tagged as the authoritative specification – and this proces is so easy to grasp and complete since it is same proces we use for source code.

One last benefit I really enjoy, one which I think is a bit underestimated is – the contract.

When we publish a public specification, we aim at to be informative, useful, correct, exact, educational, clear and to the point.

This works quite well and since often I find that we refer to the public specifications when discussing topics related to our services and since the quality of these sometime outshine our internal specifications, I often find myself thinking that we should publish much more, much much more.

So revisiting the opening paragraf – ever so often we are afraid and publishing API’s become a side-project. Do not be afraid to publish your specifications and documentation, do not be afraid to use an existing platform and toolchain, the pros outweigh the cons and you will quickly forget all about the old way of doing things and you will find yourself more productive and in the end getting your specifications published will be easier than ever.

Whether you are publishing a website or a PDF document, the information is public, the proces is actually the most important aspects and Github and Markdown REALLY leverage this.

The discussion on how far you can go and how much you can publish is a huge topic and should perhaps be another blog post.

Public Specifications FTW

TIL

I fell over something on Github called TIL (Today I Learned). I have for long pondered to migrate my notes elsewhere – currently they are all collected in a Wiki.

The idea of TIL intrigued me and now I finally got a TIL repository set up. Currently it only contains one TIL, but I plan to evaluate and migrate my earlier notes to this more open and accessible format.

Here are some of my first impressions of doing TILs hosted at Github instead of something else.

  1. The are public available
  2. They have native version control (they are actually contained in a Github repo)
  3. The can be written in Markdown
  4. They can use syntax highlighting based on the languages supported by the Github platform
  5. They follow the normal workflow used for other projects I have hosted on Github
  6. They can be forked and merged
  7. They can be commented on using issues (not directly linkable, but I guess it is somewhat trackable)
  8. Did I mention they can be written in Markdown 🙂

I have not observed any major draw-backs of this kind of write up to now, some will probably show later on, but I will give it a try and if it does not work, well I can find some other way of hosting my notes, hints, tips and tricks.

Only one TIL, but I promise more will follow.

Take care,

jonasbn

TIL

Continous Integration with Travis CI and Github for Distzillians

This post started out at a comment on a blog post, but it was simply not possible for me to comment on the relevant post, so I have edited my comment into a blog post even though most of the contents are not mine :-/

So all the Kudos, credits, beers and stuff for the contents of this post should really go to: Alex Balhatchet, read his post:

        http://blogs.perl.org/users/alex_balhatchet/2013/04/travis-ci-perl.html

Okay – I have migrated all of my CPAN distributions to Github and all new projects start up here. Over the years I have used Jenkins for continuous integration, so I was very happy when I found out that Github offered continues integration using Travis.

I had everything going with Module::Build, which have been my preferred build system and one I have been using for a long time, with Travis CI on Github, but recently I have started porting all my distributions from Module::Build to Dist::Zilla, which meant that I had to revisit my whole toolchain.

Finding Alex’s article was just what I was looking for.

The after reading Dave Cross blog post and presentation I got coverage with coveralls integrated (see my blog post on those spiffy badges)

In order to get coverage integrated with Alex’s example, I have made the following changes to his suggested setup.

install is extended with:

– cpanm –quiet –notest Devel::Cover::Report::Coveralls
– cpanm –quiet –notest Dist::Zilla::App::Command::cover

and this additional after_success section has to be added:

after_success:
– dzil cover -outputdir cover_db -report coveralls

I did run into some issues with Alex version, so I have to explicitly install Test::Kwalitee since the version on the Travis CI platform is apparently too old, so also under install I do:

– cpanm –quiet –notest Test::Kwalitee

The Test::Kwalitee issue should go away Karen Etheridge patched her Dist::Zilla plugin

An in addition I also had to install the dependencies of the plugins explicitly under install:

– dzil listdeps –author | cpanm –quiet –notest –skip-satisfied

This was due to an issue with Pod::Coverage tests, where Pod::Coverage::TrustPod.pm is missing.

You can have a look at one of my setups from my code Github:

language: perl
perl:
– “5.18”
– “5.16”
– “5.14”
– “5.12”
– “5.10”

before_install:

# Prevent “Please tell me who you are” errors for certain DZIL configs

– git config –global user.name “TravisCI”

install:

# Deal with all of the DZIL dependencies, quickly and quietly

– cpanm –quiet –notest –skip-satisfied Dist::Zilla

# Hack to getting the latest Test::Kwalitee

– cpanm –quiet –notest Test::Kwalitee

# Getting coveralls report

– cpanm –quiet –notest Devel::Cover::Report::Coveralls

# Getting cover command for Dist::Zilla

– cpanm –quiet –notest Dist::Zilla::App::Command::cover

# Getting all the plugins used by Dist::Zilla in this particular setup

– dzil authordeps | grep -vP ‘[^\w:]’ | xargs -n 5 -P 10 cpanm –quiet –notest –skip-satisfied

# Getting all the dependencies requested by author

– dzil listdeps –author | cpanm –quiet –notest –skip-satisfied

– export RELEASE_TESTING=1 AUTOMATED_TESTING=1 AUTHOR_TESTING=1 HARNESS_OPTIONS=j10:c HARNESS_TIMER=1

# Getting all the dependencies requested by distribution

– dzil listdeps | grep -vP ‘[^\w:]’ | cpanm –quiet –notest –skip-satisfied

script:

– dzil smoke –release –author

after_success:

– dzil cover -outputdir cover_db -report coveralls

Thanks to Alex Balhatchet for the post – and thanks to Dave for his awesome post and Karen for most impressive responsiveness, when reporting an issue.

Continued good day,

jonasbn, Copenhagen

Continous Integration with Travis CI and Github for Distzillians

Badges!? – we NEED stinking badges!

Spending a lot of time on Github, I observed that a lot of projects have cool badges on their pages indicating:

– build status
– coverage
– code climate

And so on…

I have been using Travis CI for my Github projects and it works like a charm. So when I fell over Dave Cross’ presentation and blog post on Travis CI and Github integration I had to read it case there was something useful I did not know and guess what there was.

Dave demonstrated how to get Travis CI and Perl on Github going, but also integrated with Coveralls and he showed how to get a coverage badge on your project.

pastedgraphic3-2014-08-8-09-26.png

AWESOME!

And in combination with the Travis CI documentation describing how to get a build status badge

pastedgraphic2-2014-08-8-09-26.png

AWESOME!

Okay, okay, two badges there most be more, so I did some googling and found CPAN badges, badges indicating the latest release to CPAN…

pastedgraphic1-2014-08-8-09-26.png

AWESOME!

All examples are taken from my Github repository Business::DK::Postalcode and you know what it even works for MetaCPAN.

jonasbn, Copenhagen

Badges!? – we NEED stinking badges!

Stranded in migration

My personal projects and code have lived a long life. I have been using RCS locally, CVS and SVN. My first public repositories was in my local Perl user group Copenhagen Perl Mongers, where we shared a central repository. It started out as CVS, but was migrated to SVN about the same time as I started uploading distributions to CPAN.

In parallel I also set up a few projects at SourceForge and later at Google Code, both using SVN (SourceForge started out as CVS for me, but migration had taken place at some point). Actually the most important project of mine there was Workflow, which was migrated from a closed SVN repository from the original author Chris Winters to SourceForge.

Anyway – for a long time I worked as a freelancer, dreaming of doing my own software instead of others. So I decided to go for a hosted solution with Versionshelf, I later changed to Atlassian, which at that time had nice product consisting of Jira, Confluence, Fisheye and Subversion (it was actually Fisheye, which let me to this, metadata on code has always intrigued me). All my new projects public and non-public got hosted here, but I still had a legacy stuck at the Copenhagen Perl Mongers Subversion server.

I got Google Code migrated to the Atlassian platform, but stayed with SourceForge because of the project organisation. The Cph.pm repos was a dead end, due to the structure, several attempts at getting the projects extracted properly was unsuccessful.

Then came Github a long and a completely new trend in VCS systems. Not always being a first mover I decided to stay put. I still wanted to migrate my old codebase, but could not find the time to sit down and do it.

Michael Schwern created Gitpan, which seemed like a nice solution, but it was based solely on the releases and a lot of history would be lost (to me a serious loss of meta data). There was even some nice blog posts on how to get the most out of Gitpan.

Workflow got migrated from SourceForge to Github, even though SourceForge hosted Git. I had experienced some issues with the administrative interfaces, which rendered the platform useless in a confusing redirect hell (this has been addressed now).

Atlassian then announced the end of life for their Subversion hosting and migration to Git (Bitbucket/Github) was possible. This was the push I needed and all of my code hosted with Atlassian got migrated, well almost all of it I still have some old customer projects still in a Subversion dump. But all of my open source projects got migrated to Github.

All my new projects now start up on Github. But still I looked at my legacy of distributions on CPAN, which I did not have active repositories for and it haunted me.

The in the summer of 2014 (this summer), I fell over Tony Bowden’s Business::Tax::VAT. I have used Business::Tax::VAT::Validation for some projects and never discovered this module, so I checked it out and it seemed that it had not had any releases in a long time and 3 our of 4 RTs was low-hanging fruit, but no Git repo.

So I mailed Tony Bowden and got COMAINT on PAUSE, we wrote back and forth about Github and we investigated the Gitpan version. Luckily the latest version on CPAN was aligned with Gitpan, so I could pick up from there. Fork, Fix and Free. Got the 3 tickets closed and shipped a release, I had to do additional release when it got picked up by the CPAN testers, but that was nothing when it was hosted on Github.

This struck me as a marvellous situation, so I went back to Gitpan and compared it’s versions of my legacy distributions which was not on Github and I was able to create forks of all of them. Yes, this would mean loss of history, but again I would much rather be able to code and maintain, than not being able to do anything.

So now all of my open source Perl projects are on Gitpan and I am a very happy camper. Maintenance releases will start to go out for most of the legacy and some will be deleted (completely) from CPAN, since they are of no value, but they will still be on BackPAN, Gitpan and for me on Github.

My legacy is under control and I am no longer stranded in migration.

jonasbn, Copenhagen

Stranded in migration

Changes and CPAN, CPAN::Changes and my Changes

Following up on the comments to my blog post on CPAN::Changes and CPAN::Changes::Spec, I created a fork of the distribution on Github and implemented a first shot for the author to evaluate. I sent the pull request yesterday, so now it will be interesting see whether it will be found useful at all.

I did a lot of thinking before starting the actual coding and I was not quite satisfied with the vocabulary I was using to describe the concept. Originally I referred to the concept as impact pointer, but it is simply misleading and not particularly descriptive. So when it occurred to me that the concept was actually hints on how the reader should view the changes and release described it came to me that the obvious name should be “update hint”.

Hints are everywhere and is the term is highly popular these days. Hints are less intrusive and in this case a much better description.

Here is an example lifted from the POD.

0.03 2010−08−01 − update recommended

− Fixed serious bug in bar method

0.02 2009−07−17 − update not required

− Added more foo() tests

0.01 2009−07−16

− Initial release

I decided for two values of the hint:

        - update recommended
        - update not required

The first for for releases, which address serious issues/bugs like security fixes, memory leaks etc. the second for releases which are housekeeping releases, updates to tests, documentation, build scripts etc.

As you can see there is no hint for the initial release. I do not want to impose my proposal on the existing specification as such and I well let it be up to the maintainer to decide whether it should be optional and what the actual values should be, my proposal works, but it just a proof of concept and in my opinion it is a nice concept I hope will be adopted.

Please feel free to evaluate my proposal for update hints in the CPAN::Changes::Spec and let me know what you think.

jonasbn, Copenhagen/Denmark

Changes and CPAN, CPAN::Changes and my Changes