# Lolcommits Sample Plugin [![Gem Version](https://img.shields.io/gem/v/lolcommits-sample_plugin.svg?style=flat)](http://rubygems.org/gems/lolcommits-sample_plugin) [![Travis Build Status](https://travis-ci.org/lolcommits/lolcommits-sample_plugin.svg?branch=master)](https://travis-ci.org/lolcommits/lolcommits-sample_plugin) [![Maintainability](https://img.shields.io/codeclimate/maintainability/lolcommits/lolcommits-sample_plugin.svg)](https://codeclimate.com/github/lolcommits/lolcommits-sample_plugin/maintainability) [![Test Coverage](https://img.shields.io/codeclimate/c/lolcommits/lolcommits-sample_plugin.svg)](https://codeclimate.com/github/lolcommits/lolcommits-sample_plugin/test_coverage) [![Gem Dependency Status](https://gemnasium.com/badges/github.com/lolcommits/lolcommits-sample_plugin.svg)](https://gemnasium.com/github.com/lolcommits/lolcommits-sample_plugin) [lolcommits](https://lolcommits.github.io/) takes a snapshot with your webcam every time you git commit code, and archives a lolcat style image with it. Git blame has never been so much fun! Lolcommit plugins are automatically loaded before the capturing process starts. The flexible class design allows developers to add features by running code before or after snapshots are taken. This gem showcases an example plugin. It prints short messages to the screen before and after every lolcommit. Something like this; ✨ Say cheese 😁 ! *** Preserving this moment in history. 📸 Snap ✨ wow! 9e6303c is your best looking commit yet! 😘 💻 Use this repo to jump-start development on your own plugin. It has tests, docs and integration with useful tools (Travis, CodeClimate, Rdoc etc.) See below for more information on how to get started. ## Developing your own plugin First, there are some things your gem *must* do to be loaded and executed correctly. At the very least: * Name your gem with the `lolcommits-` prefix. * Include a class that inherits from `Lolcommits::Plugin::Base` (this will be the entry point to your plugin from the lolcommits gem). * This main plugin class must meet the requirements explained below. * Require `lolcommits` in your gem spec as a development dependency. ### Your Plugin Class You plugin class must have a namespace and path that matches your gem name and be in the `LOAD_PATH` (required) with the gem for example: # a gem named: lolcommits-zapier # should have a plugin class inheriting from Base like so: class Lolcommits::Plugin::Zapier < Lolcommits::Plugin::Base ... end # at lib/lolcommits/plugin/zapier.rb # required in a file at lib/lolcommits/zapier.rb # or a gem named: lolcommits-super_awesome # should have a plugin class class Lolcommits::Plugin::SuperAwesome < Lolcommits::Plugin::Base ... end # required in a file at lib/lolcommits/super_awesome.rb You **should** override the following methods in this class: * `def self.name` - identifies the plugin to lolcommits and users, keep things simple and choose a name that matches your gem name. * `def self.runner_order` - return the hooks this plugin should run at during the capture process (`:pre_capture`, `:post_capture` and/or `:capture_ready`). * `def run_pre_capture`, `def run_post_capture` and/or `def run_capture_ready` - override with your plugin's behaviour. Three hooks points are available during the lolcommits capture process. * `:pre_capture` - called before the camera starts capturing, at this point you could alter the commit message/sha text. * `:post_capture` - called immediately after the camera snaps the raw image (or video for gif captures) use this hook to alter the image, other plugins may hook here to modify the image too. `:capture_ready` - called after all `:post_capture` plugins have ran, at this point the capture should be ready for exporting or sharing. ### Plugin configuration The `Base` class initializer defines an `@options` instance var, with an array of setting names that the user can configure. By default, the only option is `enabled` and plugins *must* be configured as `enabled = true` to run. A plugin can be configured by the lolcommits gem with; lolcommits --config # or lolcommits --config -p plugin-name Use the `configuration` method in your plugin class to read these options. Plugin methods you may want to override with custom configuration code include: * `def enabled?` - usually checks `configuration['enabled']` to determine if the plugin should run. * `def configure_options!` - prompts the user for configuration (based on the `@options`) returns a hash that will be persisted. * `def configured?` - checks the persisted config hash is present. * `def valid_configuration?`- checks the persisted config hash has valid data. If your plugin requires no configuration, you could override the `enabled?` method to always return `true`. Users could disable your plugin by uninstalling the gem. By default a plugin will only run it's capture hooks if: * `valid_configuration?` returns true * `enabled?` returns true For more help, check out [the documentation](http://www.rubydoc.info/github/lolcommits/lolcommits-sample_plugin/Lolcommits/Plugin/SamplePlugin) for this plugin, or take a look at [other lolcommit_plugins](https://github.com/search?q=topic%3Alolcommits-plugin+org%3Alolcommits&type=Repositories) in the wild. ### The Lolcommits 'runner' The only required argument for your plugin class initializer is a `Lolcommits::Runner` instance. By default, the base plugin initializer will set this in the `runner` instance var. Use these runner methods to access the commit, repo and configuration: * `runner.message` - the git commit message. * `runner.sha` - the git sha for the current commit. * `runner.vcs_info` - a reference to the [Lolcommits::VCSInfo](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/vcs_info.rb) instance. * `runner.config` - a reference to the [Lolcommits::Configuration](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/configuration.rb) instance. After the capturing process has completed, (i.e. in the `run_post_capture` or `run_capture_ready` hooks) these methods will reveal the captured snapshot file. * `runner.snapshot_loc` - the raw image file. * `runner.main_image` - the processed image file, resized, with text overlay applied (or any other effects from other plugins). During plugin configuration, your plugin class will be initialized with the optional `config` argument (and no runner). This allows you to read the existing saved options during configuration. E.g. to show the existing options back to the user. Take a look at the [Lolcommits::Runner](https://github.com/mroth/lolcommits/blob/master/lib/lolcommits/runner.rb) for more details. ### Testing your plugin It's a good idea to include tests with your gem. To make this easier for you, the main lolcommits gem provides helpers to work with IO and Git repos in test. # add one or both of these to your plugin's test_helper file require 'lolcommits/test_helpers/git_repo' require 'lolcommits/test_helpers/fake_io' # and include either (or both) modules in your test include Lolcommits::TestHelpers::GitRepo include Lolcommits::TestHelpers::FakeIO Use the following methods to manage a test repo: setup_repo # create the test repo commit_repo_with_message # perform a git commit in the test repo last_commit # git commit info for the last commit in the test repo teardown_repo # destroy the test repo in_repo(&block) # run lolcommits within the test repo For submitting and capturing IO use the `fake_io_capture` method. E.g. to capture the output of the `configure_options` method, while sending the string input 'true' (followed by a carriage return) when prompted on STDIN: output = fake_io_capture(inputs: %w(true)) do configured_plugin_options = plugin.configure_options! end For more examples take a look at the [tests in this repo](https://github.com/lolcommits/lolcommits-sample_plugin/blob/master/test/lolcommits/plugin/sample_plugin_test.rb) (MiniTest). ### General advice Use this gem as a starting point, renaming files, classes and references. Or build a new plugin gem from scratch with: bundle gem lolcommits-my-plugin For more examples, take a look at other published [lolcommit plugins](https://github.com/lolcommits). If you feel something is missing (or out of date) in this short guide. Please create a new [issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues). ## History Until recently, all plugins lived inside the main lolcommits gem. We are in the process of extracting them to individual gems, loaded with the new plugin manager. Ruby gem versioning will take care of managing dependencies and compatibility with the main gem. --- ## Requirements * Ruby >= 2.0.0 * A webcam * [ImageMagick](http://www.imagemagick.org) * [ffmpeg](https://www.ffmpeg.org) (optional) for animated gif capturing ## Installation Follow the [install guide](https://github.com/mroth/lolcommits#installation) for lolcommits first. Then run the following: $ gem install lolcommits-sample_plugin Next configure and enable this plugin with: $ lolcommits --config -p sample_plugin # set enabled to `true` That's it! Every lolcommit now comes with it's own short (emoji themed) message! ## Development Check out this repo and run `bin/setup`, this will install dependencies and generate docs. Run `bundle exec rake` to run all tests and generate a coverage report. You can also run `bin/console` for an interactive prompt that will allow you to experiment with the gem code. ## Tests MiniTest is used for testing. Run the test suite with: $ rake test ## Docs Generate docs for this gem with: $ rake rdoc ## Troubles? If you think something is broken or missing, please raise a new [issue](https://github.com/lolcommits/lolcommits-sample_plugin/issues). Take a moment to check it hasn't been raised in the past (and possibly closed). ## Contributing Bug [reports](https://github.com/lolcommits/lolcommits-sample_plugin/issues) and [pull requests](https://github.com/lolcommits/lolcommits-sample_plugin/pulls) are welcome on GitHub. When submitting pull requests, remember to add tests covering any new behaviour, and ensure all tests are passing on [Travis CI](https://travis-ci.org/lolcommits/lolcommits-sample_plugin). Read the [contributing guidelines](https://github.com/lolcommits/lolcommits-sample_plugin/blob/master/CONTRIBUTING.md) for more details. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. See [here](https://github.com/lolcommits/lolcommits-sample_plugin/blob/master/CODE_OF_CONDUCT.md) for more details. ## License The gem is available as open source under the terms of [LGPL-3](https://opensource.org/licenses/LGPL-3.0). ## Links * [Travis CI](https://travis-ci.org/lolcommits/lolcommits-sample_plugin) * [Test Coverage](https://codeclimate.com/github/lolcommits/lolcommits-sample_plugin/test_coverage) * [Code Climate](https://codeclimate.com/github/lolcommits/lolcommits-sample_plugin) * [RDoc](http://rdoc.info/projects/lolcommits/lolcommits-sample_plugin) * [Issues](http://github.com/lolcommits/lolcommits-sample_plugin/issues) * [Report a bug](http://github.com/lolcommits/lolcommits-sample_plugin/issues/new) * [Gem](http://rubygems.org/gems/lolcommits-sample_plugin) * [GitHub](https://github.com/lolcommits/lolcommits-sample_plugin)