Publishing to GitHub Pages Automatically

Publishing to GitHub Pages Automatically

You know, precise and correct documentation is the one kept in synch with the source code automatically.

There are many ways of doing that, many kinds of documentation. Here I’ll show you how to publish content in GitHub Pages after a successful build. In this case, the content is a API specification generated when running acceptance tests. 

How to do it?

  1. Put the content you want to be published in the /docs dir
  2. Go to Settings, find the GitHub Pages section, and select Source to master branch /docs folder, then press Save 
  3. Push it to master.

The content in the /docs will be available at or

An Example?

eHelp is configured to put its generated specs in the /docs folder. Every time we push to master, its GitHub Page gets updated. This way, its specs are always published and always in sync.

The Past – In Case You Are Curious

(It’s nice to see that things are getting simpler.)

Not so long ago, I wrote a post (Tip #1) explaining how to achieve the same result using Travis CI and some scripting help. This little project is configured the old way: see travis.yml and files.

More Help

You can find more information at GitHub help pages:

Draghi, Unicorni e Titani* – Un Racconto di un Sviluppatore Agile

Draghi, Unicorni e Titani* – Un Racconto di un Sviluppatore Agile

(Read the english version here.)

English: Cheeses and sausages from Sardinia Is...

Ho conosciuto un programmatore in Italia che stava sviluppando una applicazione per aiutare un Mercato dei Salumi e Formaggi (è così che si chiama il negozio) a meglio servire i suoi clienti.

In questo articolo provo a spiegare come lui ha riuscito a capire cos’era importante agli utenti dell’app e quali funzionalità dovrebbero essere presenti nel primo rilascio in produzione.

Questo mio collega era impegnato a sviluppare in modo incrementale basato sulle esigenze del cliente. In altre parole:

  • rilasciare una nuova versione in produzione periodicamente (diciamo ogni due settimane) con nuove funzionalità, correzioni di bug e eventuali modifiche richieste dall’utente
  • permettere all’utente di decidere (e aiutarlo a decidere) quali funzionalità devono essere consegnati prima
  • scrivere tests in modo a guidare il design e la implementazione del software (TDD).

Continue reading “Draghi, Unicorni e Titani* – Un Racconto di un Sviluppatore Agile”

Travis CI Tips

Travis CI Tips

(First of all install Travis CLI if you haven’t done it yet.)

Tip 1: Updating GitHub Project Pages Automatically after Building

Important note! There’s a much easier way of doing virtually the same thing explained here. The only difference is that GithHub Pages will only be updated if the build is green when following the instructions bellow, as opposed to updating Pages as soon as something is pushed to the branch master. 

It’s pretty nice and very rare to have documentation up-to-date with the code base. Using Yatspec, GitHub and Travis CI (all part of my current work environment), it’s easy to test, document and publish the documentation automatically after a build (like this and this), and keep the docs always in synch with the code.

Let’s Do It…

1) (Obviously) Have Some Content to Publish

As mentioned before, the content I’m interested in publishing is the specification generated by Yatspec based on acceptance tests.

2) Configure GitHub Project Pages

Continue reading “Travis CI Tips”

Iteration Zero & The Very First Release

Iteration Zero & The Very First Release

Now that we have a very good idea about what app X is all about, we can finally start writing tests and implementing functionalities. We feel very good because we are a modern agile team, with TDD, pair programming, CI, even Kanban! There is a lot of work to do. And we mean business. But how long do we take to release new features? How long do we take to release the very first one?

Delivering the first functionality involves a lot of work exactly because it’s the first time the app is going to be released in production. Just to mention a few tasks:

  • choosing all the essential libraries, tools, preferred frameworks and make them work together;
  • set up repository, continuous integration, database in the dev environment*;
  • prepare the staging environment*;
  • production environment;
  • automate deploy.

It’s common to have dev-teams developing code right after completing the 2nd or 1st task in the list, and measuring progress somehow. It certainly feels like a lot of progress is happening there (and we like to feel we are productive developers), though none of that is useful since customers can’t use the app yet.

Continue reading “Iteration Zero & The Very First Release”

Release Often & Automate Everything in the Process (beta)

Release Often & Automate Everything in the Process (beta)

(Note: this post is still in beta.) 

It’s great how easy these days is to have a work environment that supports agile process (continuous integration/delivery, [B|T]DD) almost for free.

The fact alone that all this stuff is running on someone else machine is great. But, most important, there’s no need to spend a penny or spend very little compared to having your own infrastructure and people maintaining it (even if people means just you).

Continuous Integration & Delivery

I’m using GitHub as repository, and Travis CI for continuous integration (configurable in minutes) to test and build my projects as soon as I push code to GitHub.

Continue reading “Release Often & Automate Everything in the Process (beta)”

Dragons, Unicorns and Titans* – An Agile Software Developer Tail

Dragons, Unicorns and Titans* – An Agile Software Developer Tail

(Leggi la versione italiana qui.)

English: Cheeses and sausages from Sardinia Is...

I’ve met a software engineer in Italy that was developing an application to help a Mercato dei Salumi e Formaggi to better serve their customers.

Here I tell how he managed to understand what was important to the users and which functionalities should be delivered first.

My colleague was committed to develop incrementally based on his client needs. That translates to:

  • release a new version of the application in production periodically (let’s say two weeks) with new features, bug fixes and possible changes requested by the user
  • let the user decide (and help him to decide) which features must be delivered first
  • let tests guide software design and implementation.

Continue reading “Dragons, Unicorns and Titans* – An Agile Software Developer Tail”

Rest, Json, Spring and Maven

Rest, Json, Spring and Maven

This text is about developing RESTful web services using Java, Maven, Json and Spring 3. You can read instructions on how to setup a development environment for this kind of project here. The source code is available on GitHub.


As stated in this text,

[With Rest], requests and responses are built around the transfer of representations of resources. Resources are identified by global ID’s that typically use a uniform resource identifier (URI). Client applications use Http methods (such as GET, Post, PUT, or Delete) to manipulate the resource or collection of resources. Generally, a GET method is used to get or list the resource or collection of resources, Post is used to create, PUT is used to update or replace, and Delete is for removing the resource.

The Amazing Salume Application™

You work at a small business, a supplier company specialized in the finest salumes in the world, with a few clients, mostly bistros and restaurants (actually, there are only two clients, one bistro and one restaurant, but describing the company that way makes it looks larger). They both are good clients and the sales of the company is quite impressive. As the sales are expected to continue to grow, it is time to use a software application to aid the sale process. You decided to provide a RESTful web service to allow clients to manipulate their salumes orders through requests/responses in Json format.

Continue reading “Rest, Json, Spring and Maven”

Implementing a Feature With TDD

A few days ago, I heard somebody ask “How do I start developing a functionality with TDD?” and I thought immediately that it would be a good idea to write about it.

A History

Suppose you are really popular, with thousands of friends in the Facebook, everybody in your neighborhood knows you and enjoys your company. In fact everyone in your city does.

Continue reading “Implementing a Feature With TDD”

Grammars and Parsers

Let’s build a parser to math expressions. It’s better start the job in very a simple way: process addition expressions like ‘1 + 1’.

Well… As the old Chinese saying goes, “a journey of one thousand miles begins with one tiny step”.

A Little Bit About Parsers

According to Grune and Jacobs[1]:

“Parsing is the process of structuring a linear representation in accordance with a given grammar. [..] This ‘linear representation’ may be a sentence, a computer program, [..]  in short any linear sequence in which the preceding elements in some way restrict the next element”[1, p. 3].

Example of Parsing
Image via Wikipedia

“To a computer scientist ‘1 + 2 * 3’ is a sentence in the language of ‘arithmetics on single digits’ [..], its structure can be shown, for instance, by inserting parentheses: (1 + (2 * 3)) and its semantics [i.e. its meaning] is probably 7”[1, p. 7].

We use a parser to build an expression tree. This tree contains the elements of a sentence according with the structure of a given grammar and in the correct order (afterwards we will need an interpreter that uses the tree to extract the semantic of the sentence).

And in order to implement a parser, we have to:

Continue reading “Grammars and Parsers”

Developing an Interpreter to Math Expressions

Developing an Interpreter to Math Expressions
The support vote symbol redrawn in the SVG format.
Image via Wikipedia

We’ll start slowly, only dealing with the four binary basic operations: addition, subtraction, multiplication and division. Even though we defined a concise set of operations, I need to be even more humble in order to achieve our goals, and that’s why I’ll choose one of these operations to get started with the fun.

How about we begin with the addition operation? Sounds easy good to me. Doing that will lead the way to the remainder operations (I mean subtraction, multiplication and division operations). We can represent our math expression with a limited context-free grammar like this:

MathExp -> VariableExp | Constant | AddExp | '(' MathExp ')'
AddExp -> MathExp + MathExp
VariableExp -> a | b | ... | z
Constant -> 0 | 1 | ... | 9

Let’s write a test first (using JUnit 4): if an ordinary ‘a + b’ expression with ‘a = 2’ and ‘b = 4’ must be solved, one could think in the following API (specially if you read about the GoF Interpreter pattern):

Continue reading “Developing an Interpreter to Math Expressions”