lolcommits-uploldz 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e25d6e8591f09c0f55e4b91884a3b30325ff6e60b923265bc5a578544bc45978
-  data.tar.gz: 226a8ccb7d019742ec8ac66a9dab6f003f8354a67cff30638196a3c7cf93d40e
+  metadata.gz: 9839173622884d12ac7c3f1243af76787ca33081eeb49cb5b67f574b8c6ea308
+  data.tar.gz: 7b3153491fd97da4968eb71a7115532426c96775d2c88085eac45cce4a2a30b3
 SHA512:
-  metadata.gz: a7cae83c182b5baac0f3bdce7ae2e45857a2368d39982ce11515f382ff3bd9e7565181e2bcf2116575ab828b7b86906622eff4007b4720e21e9dbff79a3d2c0d
-  data.tar.gz: 0b1c91c9a6ae28f5b03b20e2425e384f9837f88592fc82f2193e04376d16ff7fd509a2d5ab47bf534afd1f7db6767d860f9eae76afa6dbfaed2a1f2e4d62c9e1
+  metadata.gz: e54aa0308cd1017edc8535e0aa466e620a1c2151c014699a0b5af134542549baccf091673893987604426ca019c753a1792195be1b9a680b68de5adc9694d88e
+  data.tar.gz: 86166151ae1810ebd6a21482b0855b4fc34e7eb79cf05a66c75a0e537b09cfd0a4b534c81026cb823637fff6f311cb8ac203f0aed1acd8cfeac6e898af5663ec

data/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_ONLY: rubocop
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Ruby and install gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3.0
+          bundler-cache: true
+      - name: Run Rubocop
+        run: bundle exec rubocop --parallel
+  test:
+    name: ${{ format('Unit tests (Ruby {0})', matrix.ruby-version) }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version:
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "3.4"
+    continue-on-error: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Ruby and install gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Configure Git
+        run: |
+          git config --global user.name $NAME
+          git config --global user.email $EMAIL
+        env:
+          NAME: "George Costanza"
+          EMAIL: "george.costanza@vandelay.com"
+      - name: Run tests
+        run: bundle exec rake test

data/.quickhook/pre-commit/ruby-lint

@@ -0,0 +1,3 @@
+#!/bin/sh
+set -e
+grep -E "\.rb$|Rakefile|Gemfile" | xargs ./bin/rubocop --config .rubocop.yml --force-exclusion

data/.rubocop.yml

@@ -0,0 +1,2 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml

data/CHANGELOG.md

@@ -9,6 +9,11 @@ adheres to [Semantic Versioning][Semver].
 
 - Your contribution here!
 
+## [0.6.1] - 2024-12-29
+### Changed
+- Push gems with bundler (not GitHub actions)
+- Updated documentation links
+
 ## [0.6.0] - 2024-09-24
 ### Removed
 - Support for Ruby < 3.1 (older rubies no longer supported)
@@ -70,7 +75,8 @@ adheres to [Semantic Versioning][Semver].
 ### Changed
 - Initial release
 
-[Unreleased]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/lolcommits/lolcommits-uploldz/compare/v0.3.0...v0.4.0

data/Gemfile

@@ -1,2 +1,6 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 gemspec
+
+group :rubocop do
+  gem "rubocop-rails-omakase", require: false
+end

data/README.md

@@ -1,16 +1,16 @@
 # Lolcommits Uploldz
 
-[![Build](https://img.shields.io/github/actions/workflow/status/lolcommits/lolcommits-uploldz/build.yml?branch=main&style=flat)](https://github.com/lolcommits/lolcommits-uploldz/actions/workflows/build.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/lolcommits/lolcommits-uploldz/ci.yml?branch=main&style=flat&label=CI)](https://github.com/lolcommits/lolcommits-uploldz/actions/workflows/ci.yml)
 [![Gem](https://img.shields.io/gem/v/lolcommits-uploldz.svg?style=flat)](http://rubygems.org/gems/lolcommits-uploldz)
 [![Depfu](https://img.shields.io/depfu/lolcommits/lolcommits-uploldz.svg?style=flat)](https://depfu.com/github/lolcommits/lolcommits-uploldz)
 
-[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!
+[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!
 
-This plugin uploads each lolcommit to a remote server after capturing.
-You configure the plugin by setting a remote endpoint to handle the HTTP
-post request. The following params will be sent:
+This plugin uploads each lolcommit to a remote server after capturing.  You
+configure the plugin by setting a remote endpoint to handle the HTTP post
+request. The following params will be sent:
 
 * `file` - captured lolcommit file
 * `message` - the commit message
@@ -20,8 +20,7 @@ post request. The following params will be sent:
 * `author_email` - the commit author email address
 * `key` - optional key (string) from plugin config
 
-You can also set an optional HTTP Basic Auth header (username and/or
-password).
+You can also set an optional HTTP Basic Auth header (username and/or password).
 
 ## Requirements
 
@@ -43,19 +42,19 @@ Then configure to enable and set the remote endpoint:
     # set the remote endpoint (must begin with http(s)://)
     # optionally set a key (sent in params) and/or HTTP Basic Auth credentials
 
-That's it! Provided the endpoint responds correctly, your next lolcommit
-will be uploaded to it. To disable use:
+That's it! Provided the endpoint responds correctly, your next lolcommit will be
+uploaded to it. To disable use:
 
     $ lolcommits --config -p uploldz
     # and set enabled to `false`
 
 ## Development
 
-Check out this repo and run `bin/setup`, this will install all
-dependencies and generate docs. Use `bundle exec rake` to run all tests.
+Check out this repo and run `bin/setup`, this will install all dependencies and
+generate docs. Use `bundle exec rake` to run all tests.
 
-You can also run `bin/console` for an interactive prompt that will allow
-you to experiment with the gem code.
+You can also run `bin/console` for an interactive prompt that will allow you to
+experiment with the gem code.
 
 ## Tests
 
@@ -72,27 +71,23 @@ Generate docs for this gem with:
 ## Troubles?
 
 If you think something is broken or missing, please raise a new
-[issue](https://github.com/lolcommits/lolcommits-uploldz/issues). Take a
-moment to check it hasn't been raised in the past (and possibly closed).
+[issue](https://github.com/lolcommits/lolcommits-uploldz/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-uploldz/issues)
-and [pull
-requests](https://github.com/lolcommits/lolcommits-uploldz/pulls) are
-welcome on GitHub.
+Bug [reports](https://github.com/lolcommits/lolcommits-uploldz/issues) and [pull
+requests](https://github.com/lolcommits/lolcommits-uploldz/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.com/lolcommits/lolcommits-uploldz). Read the
-[contributing
-guidelines](https://github.com/lolcommits/lolcommits-uploldz/blob/master/CONTRIBUTING.md)
+When submitting pull requests, remember to add tests covering any new behaviour,
+and ensure all tests are passing. Read the [contributing
+guidelines](https://github.com/lolcommits/lolcommits-loltext/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
+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-uploldz/blob/master/CODE_OF_CONDUCT.md)
 for more details.
 
@@ -103,8 +98,8 @@ The gem is available as open source under the terms of
 
 ## Links
 
-* [CI](https://github.com/lolcommits/lolcommits-uploldz/actions/workflows/build.yml)
-* [RDoc](http://rdoc.info/projects/lolcommits/lolcommits-uploldz)
+* [CI](https://github.com/lolcommits/lolcommits-uploldz/actions/workflows/ci.yml)
+* [RDoc](https://rubydoc.info/gems/lolcommits-uploldz)
 * [Issues](http://github.com/lolcommits/lolcommits-uploldz/issues)
 * [Report a bug](http://github.com/lolcommits/lolcommits-uploldz/issues/new)
 * [Gem](http://rubygems.org/gems/lolcommits-uploldz)

data/Rakefile

@@ -18,4 +18,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => ['test']
+task default: [ "test" ]

data/bin/rubocop

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+load Gem.bin_path("rubocop", "rubocop")

data/lib/lolcommits/plugin/uploldz.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require 'rest_client'
-require 'base64'
-require 'lolcommits/plugin/base'
+require "rest-client"
+require "base64"
+require "lolcommits/plugin/base"
 
 module Lolcommits
   module Plugin
     class Uploldz < Base
-
       attr_accessor :endpoint
 
       ##
@@ -96,7 +95,7 @@ module Lolcommits
         password = configuration[:optional_http_auth_password]
         return unless user || password
 
-        'Basic ' + Base64.encode64("#{user}:#{password}").chomp
+        "Basic " + Base64.encode64("#{user}:#{password}").chomp
       end
     end
   end

data/lib/lolcommits/uploldz/version.rb

@@ -2,6 +2,6 @@
 
 module Lolcommits
   module Uploldz
-    VERSION = "0.6.0".freeze
+    VERSION = "0.6.1".freeze
   end
 end

data/lib/lolcommits/uploldz.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
-require 'lolcommits/uploldz/version'
-require 'lolcommits/plugin/uploldz'
+require "lolcommits/uploldz/version"
+require "lolcommits/plugin/uploldz"

data/lolcommits-uploldz.gemspec

@@ -5,9 +5,9 @@ require 'lolcommits/uploldz/version'
 Gem::Specification.new do |spec|
   spec.name     = "lolcommits-uploldz"
   spec.version  = Lolcommits::Uploldz::VERSION
-  spec.authors  = ["Matthew Hutchinson"]
-  spec.email    = ["matt@hiddenloop.com"]
-  spec.summary  = %q{Uploads lolcommits to a remote server}
+  spec.authors  = [ "Matthew Hutchinson" ]
+  spec.email    = [ "matt@hiddenloop.com" ]
+  spec.summary  = %q(Uploads lolcommits to a remote server)
   spec.homepage = "https://github.com/lolcommits/lolcommits-uploldz"
   spec.license  = "LGPL-3.0"
 
@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata = {
     "homepage_uri"      => "https://github.com/lolcommits/lolcommits-uploldz",
+    "documentation_uri" => "https://rubydoc.info/gems/lolcommits-uploldz",
     "changelog_uri"     => "https://github.com/lolcommits/lolcommits-uploldz/blob/master/CHANGELOG.md",
     "source_code_uri"   => "https://github.com/lolcommits/lolcommits-uploldz",
     "bug_tracker_uri"   => "https://github.com/lolcommits/lolcommits-uploldz/issues",
@@ -28,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = `git ls-files -- {test,features}/*`.split("\n")
   spec.bindir        = "bin"
   spec.executables   = []
-  spec.require_paths = ["lib"]
+  spec.require_paths = [ "lib" ]
 
   spec.required_ruby_version = ">= 3.1"
 

data/test/lolcommits/plugin/uploldz_test.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+describe Lolcommits::Plugin::Uploldz do
+  include Lolcommits::TestHelpers::GitRepo
+  include Lolcommits::TestHelpers::FakeIO
+
+  def valid_enabled_config
+    {
+      enabled: true,
+      endpoint: "https://uploldz.com/uplol",
+      optional_http_auth_username: "joe",
+      optional_http_auth_password: "1234"
+    }
+  end
+
+  describe "initalizing" do
+    it "assigns runner and all plugin options" do
+      _(plugin.runner).wont_be_nil
+      _(plugin.options).must_equal [
+        :enabled,
+        :endpoint,
+        :optional_key,
+        :optional_http_auth_username,
+        :optional_http_auth_password
+      ]
+    end
+  end
+
+  describe "#enabled?" do
+    it "is false by default" do
+      _(plugin.enabled?).must_equal false
+    end
+
+    it "is true when configured" do
+      plugin.configuration = valid_enabled_config
+      _(plugin.enabled?).must_equal true
+    end
+  end
+
+  describe "run_capture_ready" do
+    before { commit_repo_with_message("first commit!") }
+    after { teardown_repo }
+
+    it "syncs lolcommits" do
+      captured_img_path = File.expand_path("./test/images/lolcommit.jpg")
+
+      in_repo do
+        plugin.configuration = valid_enabled_config
+        plugin.runner.lolcommit_path = captured_img_path
+
+        stub_request(:post, "https://uploldz.com/uplol").to_return(status: 200)
+
+        plugin.run_capture_ready
+
+        assert_requested :post, "https://uploldz.com/uplol", times: 1,
+          headers: { "Content-Type" => /multipart\/form-data/ } do |req|
+          _(req.body).must_match(/Content-Disposition: form-data;.+name="file"; filename="lolcommit.jpg"/)
+          _(req.body).must_match 'name="repo"'
+          _(req.body).must_match 'name="author_name"'
+          _(req.body).must_match 'name="author_email"'
+          _(req.body).must_match 'name="sha"'
+          _(req.body).must_match 'name="key"'
+          _(req.body).must_match "plugin-test-repo"
+          _(req.body).must_match "first commit!"
+        end
+      end
+    end
+  end
+
+  describe "configuration" do
+    it "allows plugin options to be configured" do
+      # enabled, endpoint, key, user, password
+      inputs = %w[
+        true
+        https://my-server.com/uplol
+        key-123
+        joe
+        1337pass
+      ]
+      configured_plugin_options = {}
+
+      fake_io_capture(inputs: inputs) do
+        configured_plugin_options = plugin.configure_options!
+      end
+
+      _(configured_plugin_options).must_equal({
+        enabled: true,
+        endpoint: "https://my-server.com/uplol",
+        optional_key: "key-123",
+        optional_http_auth_username: "joe",
+        optional_http_auth_password: "1337pass"
+      })
+    end
+
+    describe "#valid_configuration?" do
+      it "returns false for an invalid configuration" do
+        plugin.configuration = { endpoint: "gibberish" }
+        _(plugin.valid_configuration?).must_equal false
+      end
+
+      it "returns true with a valid configuration" do
+        plugin.configuration = valid_enabled_config
+        _(plugin.valid_configuration?).must_equal true
+      end
+    end
+  end
+
+  private
+    def plugin
+      @plugin ||= Lolcommits::Plugin::Uploldz.new(
+        runner: Lolcommits::Runner.new
+      )
+    end
+end

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+
+# lolcommits gem
+require "lolcommits"
+
+# lolcommit test helpers
+require "lolcommits/test_helpers/git_repo"
+require "lolcommits/test_helpers/fake_io"
+
+# plugin gem test libs
+require "lolcommits/uploldz"
+require "webmock/minitest"
+require "minitest/autorun"
+
+# swallow all debug output during test runs
+def debug(msg); end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lolcommits-uploldz
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Matthew Hutchinson
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-28 00:00:00.000000000 Z
+date: 2024-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -103,35 +103,38 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/build.yml"
-- ".github/workflows/push_gem.yml"
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".simplecov"
-- ".travis.yml"
+- ".quickhook/pre-commit/ruby-lint"
+- ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE
-- PULL_REQUEST_TEMPLATE.md
 - README.md
 - Rakefile
 - bin/console
+- bin/rubocop
 - bin/setup
 - lib/lolcommits/plugin/uploldz.rb
 - lib/lolcommits/uploldz.rb
 - lib/lolcommits/uploldz/version.rb
 - lolcommits-uploldz.gemspec
+- test/images/lolcommit.jpg
+- test/lolcommits/plugin/uploldz_test.rb
+- test/test_helper.rb
 homepage: https://github.com/lolcommits/lolcommits-uploldz
 licenses:
 - LGPL-3.0
 metadata:
   homepage_uri: https://github.com/lolcommits/lolcommits-uploldz
+  documentation_uri: https://rubydoc.info/gems/lolcommits-uploldz
   changelog_uri: https://github.com/lolcommits/lolcommits-uploldz/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/lolcommits/lolcommits-uploldz
   bug_tracker_uri: https://github.com/lolcommits/lolcommits-uploldz/issues
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,8 +149,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Uploads lolcommits to a remote server
-test_files: []
+test_files:
+- test/images/lolcommit.jpg
+- test/lolcommits/plugin/uploldz_test.rb
+- test/test_helper.rb

data/.github/workflows/build.yml

@@ -1,34 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        ruby-version: ['3.1', '3.2', '3.3', '3.4']
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true
-    - name: Configure git user name, email
-      run: |
-        git config --global user.name $NAME
-        git config --global user.email $EMAIL
-      env:
-        NAME: "George Costanza"
-        EMAIL: "george.costanza@vandelay.com"
-    - name: Run tests
-      run: bundle exec rake test

data/.github/workflows/push_gem.yml

@@ -1,25 +0,0 @@
-name: Publish gem to RubyGems.org
-
-on:
-  push:
-    tags:
-      - v*
-
-jobs:
-  push:
-    name: Push gem to RubyGems.org
-    runs-on: ubuntu-latest
-
-    permissions:
-      id-token: write
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          bundler-cache: true
-          ruby-version: ruby
-
-      - uses: rubygems/release-gem@v1

data/.simplecov

@@ -1,9 +0,0 @@
-SimpleCov.start do
-  add_filter '/test/'
-  add_filter '/vendor/'
-end
-
-SimpleCov.at_exit do
-  SimpleCov.result.format!
-  `open ./coverage/index.html` if RUBY_PLATFORM =~ /darwin/
-end

data/.travis.yml

@@ -1,29 +0,0 @@
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.4.9
-  - 2.5.7
-  - 2.6.5
-  - 2.7.1
-  - ruby-head
-
-before_install:
-  - git --version
-  - git config --global user.email "lol@commits.org"
-  - git config --global user.name "Lolcommits"
-
-matrix:
-  allow_failures:
-    - rvm: ruby-head
-
-env:
-  global:
-    - CC_TEST_REPORTER_ID=a11f4b88e9bad7b922ca0ce5c70e369d1fd704c1b7c08c5b9e273e29a8c73345
-    - GIT_COMMITTED_AT=$(if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then git log -1 --pretty=format:%ct; else git log -1 --skip 1 --pretty=format:%ct; fi)
-before_script:
-  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-  - chmod +x ./cc-test-reporter
-  - ./cc-test-reporter before-build - GIT_COMMITTED_AT=$(if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then git log -1 --pretty=format:%ct; else git log -1 --skip 1 --pretty=format:%ct; fi)
-after_script:
-  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/PULL_REQUEST_TEMPLATE.md

@@ -1,16 +0,0 @@
-
-Explain what you're changing and why here.
-
----
-#### :memo: Checklist
-
-Please check this list and leave it intact for the reviewer. Thanks! :heart:
-
-- [ ] Commit messages provide context (why not just what, some tips [here](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)).
-- [ ] If relevant, mention GitHub issue number above and include in a commit message.
-- [ ] Latest code from master merged.
-- [ ] New behaviour has test coverage.
-- [ ] Avoid duplicating code.
-- [ ] No commented out code.
-- [ ] Avoid comments for your code, write code that explains itself.
-- [ ] Changes are simple, useful, clear and brief.