Easy project history with Conventional Changelog Ruby

Now and then we want to know the evolution of a software we are working on. For some time I thought the Git log of a project was enough, but the truth is there is much noise in there. In addition to the noise, depending of the project, sometimes some not no techie people need to read the product history and doing a git log is not an option for them. A solution many people found for these problems is to keep a changelog file.

For a long time, the problem with changelogs was that they were hard and expensive to maintain, too much time was needed. Fortunately, the AngularJS community created some Git commit message conventions. Definition is a step for automation and Node.js conventional-changelog was created. The main problem with the Node.js version of the conventional changelog is that it doesn’t have an executable and many of my projects are not in Node.js . There is also a Grunt version, but I don’t want to add a Gruntfile to many Ruby projects just to be able to generate a changelog. I thought about creating a pull request adding an executable to the Node.js version, but I also wanted to be able to generate changelogs by dates, not just versions, as until now I haven’t need to use versions in web applications and separating the changes by date seems more natural to me.

Conventional Changelog Ruby was born a tool to easily generate changelogs with Rubygems and Git as the only dependencies. A big addition over the other versions is that changelogs by date are also supported. For more and up to date info, please refer to the README.


Ruby annotations

In the programming world, an annotation is a way to mark the code that is below it for many purposes. In Cucumber, the tags it uses are a kind of annotation to apply callbacks and classify some features and scenarios:

Feature: Verify billing
  Scenario: Missing product description
  Scenario: Several products

In the case of VRaptor, we can use annotations to specify a controller as a REST resource or to restrict the access method to an action:

public class ShoppingCartController {
public class ProductsController {
    public void add(Product product) {...}

In the Ruby language, two annotations that are very used are the methods protected and private, which without arguments restrict the visibility of the methods defined below them:

class User
  def jump; end;
  def eat; end;
  def flirt; end;
  def sleep; end;
  def dream; end;

In some situations we may want to annotate our code like this, for example to specify that a method is deprecated, functionality that is offered by the gem Canivete from Douglas Campos:

class Bomb
  def explode; end

In the previous code, when somebody calls Bomp#explode, the interpreter will effectively execute the method, but also will output: Warning: calling deprecated method Bomb.explode.

The key to this behavior is the method_added method which is present in all Ruby modules and which is called every time a method is defined, receiving the name of the method as the parameter.

We can use this method, for example, to create an annotation that specifies that the methods declared below it can only be called by an admin, something like this:

class Module
  def method_added(name)
    unless @_admin_only.nil? or @_proxy_method
      @_proxy_method = true
      alias_method "_admin_#{name}", name
      module_eval <<-STRING
        def #{name}(*args, &block)
          _admin_#{name}(*args, &block) if admin?
      @_proxy_method = false
  def admin_only
    @_admin_only = true
class User
  def admin?
    [true, false][rand(2)]
  def update_password
    puts "password updated"
  def restart_server
    puts "server restarted"

In the previous code, #admin? will randonmly return true or false and depending of the result the called method will be executed or not.