caretaker-core

Overview

caretaker Core is the brain that makes Sonny work, it processes the git log for a given repository and returns all of the required information as a single JSON object.

Sonny makes use of this object in order to dynamically build a CHANGELOG.md file for the given project.

Installation

Add this line to your application's Gemfile:

gem 'caretaker-core'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install caretaker-core

Usage

The following is a very simple snippet showing how to integrate the core into your own code. The key is the single call to caretakerCore.run.

#!/usr/bin/env ruby

require 'json'
require 'caretaker-core'

begin
    results = caretakerCore.run
rescue StandardError => e
    puts e.message
    exit
end

puts JSON.pretty_generate(JSON.parse(results))

Output

The output from caretakerCore.run is a JSON formatted object. In the case of an error it will raise a StandardError.

The basic structure of the JSON is as follows:

{
    "tags": [ ],
    "commits": {
        "chronological": { },
        "categorised": { },
    },
    "repo": {
        "url": "",
        "slug": ""
    }
}

• tags - An array of tag names, it will also include 'untagged' for all commits that are not part of a tag.
• commits - A hash with 2 elements
  • chronological - All commits in chronological order.
  • categorised - All commits split by category.
• repo - A hash with information relating to the repository
  • url - The full base url to the repo (e.g. https://github.com/DevelopersToolbox/caretaker-core)
  • slug - The github organisation / repository name (e.g. DevelopersToolbox/caretaker-core)

A more full example (Showing a single commit)

{
    "tags": [
        "untagged"
    ],
    "commits": {
        "chronological": {
            "untagged": [
                {
                    "hash": "11781d3",
                    "hash_full": "11781d3cbdac68a003492fc0d318d402dd241579",
                    "subject": "The initial commit",
                    "extra": false,
                    "commit_type": "commit",
                    "category": "Uncategorised:",
                    "date": "2021-03-03"
                }
            ]
        },
        "categorised": {
            "untagged": {
                "New Features:": [ ],
                "Improvements:": [ ],
                "Bug Fixes:": [ ],
                "Security Fixes:": [ ],
                "Refactor:": [ ],
                "Style:": [ ],
                "Deprecated:": [ ],
                "Removed:": [ ],
                "Tests:": [ ],
                "Documentation:": [ ],
                "Chores:": [ ],
                "Experiments:": [ ],
                "Miscellaneous:": [ ],
                "Uncategorised:": [
                    {
                        "hash": "11781d3",
                        "hash_full": "11781d3cbdac68a003492fc0d318d402dd241579",
                        "subject": "The initial commit",
                        "extra": false,
                        "commit_type": "commit",
                        "category": "Uncategorised:",
                        "date": "2021-03-03"
                    }
                ],
                "Initial Commit:": [ ],
                "Skip:": [ ]
            }
        }
    },
    "repo": {
        "url": "https://github.com/DevelopersToolbox/caretaker-core",
        "slug": "DevelopersToolbox/caretaker-core"
    }
}

Other Values

Name	Purpose	Possible Values
hash	Stores the short hash for the commit.	7 character hexidecimal string
hash_full	Stores the full hash for the commit.	40 character hexodecimal string
commit_message	The commit message message.	Anything alphanumberic
child_commit_messages	The commit messages of any commits that form part of a pull/merge request	Anything alphanumberic or false
commit_type	The type of commit	pr or commit
category	The category the commit belongs to	Category List
date	The date the commit was made	YYYY-MM-DD format

For more information about the use of categories - please refer to the sonny documentation.

Limitations with regards to Pull Requests

1. Squished commits work as exepected and the contents of the child commmits is available
2. Rebased commits show as local commits as there is no way to see where they came from
3. Unsquished commits only show the PR commit_message as the child commits are ignored

Our advice is to always use Squished commits.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributors

Show Support