git-semaphore 0.0.9 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b86473a790890b9ce221b9f1a41143a6b11c63ee
-  data.tar.gz: cf5a879705922db3a175eb1294df94fda33cde54
+  metadata.gz: 796fce310598b663f7a73fa5f98d68602de41bf6
+  data.tar.gz: 25ace2adb5a1a3f245ab1a02c9f86553917d0550
 SHA512:
-  metadata.gz: 72be87873ee8f9ac9dc50780560bf04a086c2238f7aa73eb1ff8b83971a9e13f18ca2b466f813bdc00e15c14e062b76f01f41c95f18834d74f36d660bb590161
-  data.tar.gz: 1e9f18f4dd33f89ca2c895ea274ebee95f826b0706c1e968dfcaa3a0cc8e171510ad311f15a6e75dadbaffea31a0672af62a9ebefbc1910771008705175e96ff
+  metadata.gz: 24e942d6b710d328183c42d89937ca5e80c2c51ed5dc2d3e5f5cea4780bd3b1b2ad890c3bfb43d01a55dbcbcb2b7b4bba889e1adb7473562662d4ad00bc488b0
+  data.tar.gz: 168659a4950ecdba848365456bea3052ca393734cf72e942affdf81e859fbdfb139067a303e21b5ee44124f1143030b450e69df4a338f0996ce54739ede739f4

data/.gitignore

@@ -1,19 +1,9 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*.sublime-*
-vcr_debug.log
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.pryrc

@@ -0,0 +1,6 @@
+# this loads all of "git semaphore"
+load "exe/git-semaphore" unless Kernel.const_defined? 'Git::Semaphore'
+
+# utility function to set pry context
+# to an instance of <Git::Semaphore::App>
+def app() pry Git::Semaphore::App.new(Git::Semaphore.auth_token, Git::Semaphore.git_repo, ENV) ; end

data/.ruby-version

@@ -1 +1 @@
-2.0.0-p598
+2.3.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at peter.vandenberk@simplybusiness.co.uk. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/LICENSE.txt

@@ -1,22 +1,21 @@
-Copyright (c) 2012 Peter Vandenberk
+The MIT License (MIT)
 
-MIT License
+Copyright (c) 2012-2016 Peter Vandenberk
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,84 +1,210 @@
 # Git::Semaphore
 
-[![Build Status](https://semaphoreci.com/api/v1/projects/03b2dffc7112138851166c86adb456484426a712/7753/badge.png)](https://semaphoreci.com/pvdb/git-semaphore)
+[![Build Status](https://semaphoreci.com/api/v1/pvdb/git-semaphore/branches/master/badge.svg)](https://semaphoreci.com/pvdb/git-semaphore)
 
 [![Travis CI](https://travis-ci.org/pvdb/git-semaphore.svg?branch=v0.0.6)](https://travis-ci.org/pvdb/git-semaphore)
 
-git integration with [semaphoreci.com][] (via their API)
+Integrate git repositories with their corresponding project on [semaphoreci.com][] _(via the semaphore API)_
+
+## Features
+
+* highly opiniated
+* integrated with `git`
+* caching of API results
+* pagination of API calls
+* enrichment of API data
+* extensive API feature support
+* support for multiple Semaphore accounts
+
+## Semaphore API support
+
+The following sections of the [Semaphore API][] are fully or partially supported by `git semaphore`:
+
+| API section        |    | summary |
+|--------------------|----|---------|
+| [authentication][]      | ✅ | API authentication                    |
+| [projects][]            | ✅ | listing projects                      |
+| [branches and builds][] | ✅ | querying branches and managing builds |
+| [servers and deploys][] | ❌ | querying servers and managing deploys |
+| [webhooks][]            | ❌ | listing and managing webhooks         |
+
+[authentication]:      https://semaphoreci.com/docs/api_authentication.html
+[projects]:            https://semaphoreci.com/docs/projects-api.html
+[branches and builds]: https://semaphoreci.com/docs/branches-and-builds-api.html
+[servers and deploys]: https://semaphoreci.com/docs/servers-and-deploys-api.html
+[webhooks]:            https://semaphoreci.com/docs/webhooks-api.html
+
+The following [Semaphore API][] features are supported by `git semaphore`:
+
+| API feature      |    | command |summary |
+|------------------|----|---------|--------|
+| [authentication][]    | ✅ |                            | provide user authentication via an authentication token            |
+| [projects][]          | ✅ | `git semaphore --projects` | list all projects and their current status                         |
+| [project branches][]  | ✅ | `git semaphore --branches` | list all branches for the current project                          |
+| [branch status][]     | ✅ | `git semaphore --status`   | list the build status for the current branch                       |
+| [branch history][]    | ✅ | `git semaphore --history`  | list the build history for the current branch                      |
+| [build information][] | ❌ |                            | detailed information for a given build number                      |
+| [build log][]         | ❌ |                            | execution logs for a given build number _(per thread and command)_ |
+| [rebuild][]           | ✅ | `git semaphore --rebuild`  | rebuild last revision for the current branch                       |
+| [launch build][]      | ❌ |                            | launch a build for the given commit SHA                            |
+| [stop][]              | ❌ |                            | stop an in-progress build                                          |
+| [deploy][]            | ❌ |                            | run a deploy from a given build                                    |
+
+[project branches]:  https://semaphoreci.com/docs/branches-and-builds-api.html#project_branches
+[branch status]:     https://semaphoreci.com/docs/branches-and-builds-api.html#branch_status
+[branch history]:    https://semaphoreci.com/docs/branches-and-builds-api.html#branch_history
+[build information]: https://semaphoreci.com/docs/branches-and-builds-api.html#build_information
+[build log]:         https://semaphoreci.com/docs/branches-and-builds-api.html#build_log
+[rebuild]:           https://semaphoreci.com/docs/branches-and-builds-api.html#rebuild
+[launch build]:      https://semaphoreci.com/docs/branches-and-builds-api.html#launch_build
+[stop]:              https://semaphoreci.com/docs/branches-and-builds-api.html#stop
+[deploy]:            https://semaphoreci.com/docs/branches-and-builds-api.html#deploy
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install the gem:
 
-    gem 'git-semaphore'
+    gem install git-semaphore
 
-And then execute:
+And execute it as a `git` subcommand:
 
-    $ bundle
+    git semaphore <options>
 
-Or install it yourself as:
+To get an overview of the available options, use:
 
-    $ gem install git-semaphore
+    git-semaphore --help
 
-## Authentication
+## API authentication
 
-Log into [semaphoreci.com][] and find your API `authentication token` in the `API` tab of one of your projects' `settings` page.
+Log into [semaphoreci.com][] and find **your authentication token** at the bottom of your [account settings][] page... this is also explained in [the Semaphore API documentation][authentication].
 
-Next, choose one of the following mechanisms to make your API `authentication token` available to `Git::Semaphore`...
+Next, choose one of the following mechanisms to make your API authentication token available to `git semaphore`...
+
+### via *local* git config _(in a git working dir)_
+
+    git config --local --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+
+### via *global* git config
+
+    git config --global --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
 
 ### via an environment variable
 
-    $ export SEMAPHORE_AUTH_TOKEN="Yds3w6o26FLfJTnVK2y9"
+    export SEMAPHORE_AUTH_TOKEN="Yds3w6o26FLfJTnVK2y9"
+
+This is also the order in which tokens are searched for - and hence their precedence - meaning that if you have different Semaphore accounts for different projects _(e.g. work and personal projects)_ then you can configure your respective git repos with the authentication token of the corresponding Semaphore account.
+
+## API result caching
+
+For performance reasons _(especially for Semaphore API calls that are paginated)_, to enable offline use of the Semaphore API data, as well as to support interactive use of the data in e.g. `irb` or `pry` sessions, `git semaphore` transparently caches the results of all API calls in the `${HOME}/.git/semaphore/` directory.
+
+This means that running `git semaphore` commands may return stale data, in cases where things have changed on `semaphoreci.com` since the last time `git semaphore` was run.
+
+To delete the cache - and force a refresh of the Semaphore data on the next API call - use the `git semaphore --clean` command... this will empty out the entire `${HOME}/.git/semaphore` cache directory.
+
+## Integration with `git`
+
+When used inside a git repository, `git semaphore` uses [convention over configuration][coc] to figure out the relevant settings it needs in order to make valid Semaphore API requests:
+
+| setting      | inside git repo    | pseudo-code                     | override                        |
+|--------------|--------------------|---------------------------------|---------------------------------|
+| project name | derived from pwd   | `File.basename(Dir.pwd)`        | `ENV['SEMAPHORE_PROJECT_NAME']` |
+| branch name  | current git branch | `git symbolic-ref --short HEAD` | `ENV['SEMAPHORE_BRANCH_NAME']`  |
+| commit SHA   | current git head   | `git rev-parse HEAD`            | `ENV['SEMAPHORE_COMMIT_SHA']`   |
+
+However, each of these defaults can be overridden by setting the corresponding environment variable, as documented in the above table.  The same `ENV`-based override mechanism can be leveraged to use `git semaphore` outside of a git repository.
+
+The `git semaphore --settings` command can be used to print out the values for these various settings:
+
+    $ git semaphore --settings | jq '.'
+    {
+      "semaphore_auth_token": "Yds3w6o26FLfJTnVK2y9",
+      "semaphore_project_name": "git-semaphore",
+      "semaphore_branch_name": "master",
+      "semaphore_commit_sha": "4b59c3e41ca4592dfb01f77f2163154f3d3532fe"
+    }
+    $ _
+
+## Available commands
 
-### via `local` git config _(in a git working dir)_
+> ⚠️ all of the below examples need to be run from within a git repository ⚠️
 
-    $ git config --local --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+### list the Semaphore settings
 
-### via `global` git config
+    git semaphore --settings
 
-    $ git config --global --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+_(lists things like project name, branch name, commit SHA, etc.)_
 
-## Usage
+### open the Semaphore page for the project's current branch
 
-All of the below examples need to be run from within a git directory.
+    git semaphore --browse
 
-### listing of user's projects
+_(the project and branch names are derived from the current git repository and the current git head)_
 
-    $ git semaphore --projects
+### delete the local Semapore API cache
 
-### listing of project's branches
+    git semaphore --clean
 
-    $ git semaphore --branches
+ _(this ensures the Semaphore data is refreshed for the subsequent API calls)_
+
+### list all Semaphore projects
+
+    git semaphore --projects
+
+_(for the Semaphore user account corresponding to the authentication token)_
+
+### list all of the project's branches
+
+    git semaphore --branches
 
 _(the project name is derived from the current git directory)_
 
-### status of a project's branch
+### build status of the project's current branch
+
+    git semaphore --status
+
+_(the project and branch names are derived from the current git repository and the current git head)_
+
+### build history of a project's branch
 
-    $ git semaphore --status
+    git semaphore --history
 
-_(the project and branch name are derived from the current git directory and the current git head)_
+_(the project and branch names are derived from the current git repository and the current git head)_
 
-### formatting the raw `git semaphore` JSON output
+## Formatting the raw `git semaphore` JSON output
 
-After installing the quite brilliant [jazor gem][jazor] (`gem install jazor`), the `jazor` utility can be used to format the raw JSON output generated by the various `git semaphore` commands, as follows:
+After installing [the indispensable jq utility][jq] (`brew install jq`), the raw JSON output generated by the various `git semaphore` commands can be formatted and queried as follows:
 
-    $ git semaphore --projects | jazor -c
-    $ git semaphore --branches | jazor -c
-    $ git semaphore --status | jazor -c
+    # pretty-print the git semaphore settings
+    git semaphore --settings | jq '.'
+
+    # list the full name of all Semaphore projects
+    git semaphore --projects | jq -r '.[] | .full_name'
+
+    # get the status of the last build for the current branch
+    git semaphore --status | jq -r '.result'
+
+    # list the build duration (in minutes) for all "passed" builds of the current branch
+    git semaphore --history | jq -r '.builds | .[] | select(.result == "passed") | (.build_number|tostring) + "\t" + (.duration.minutes|tostring)'
+
+[semaphoreci.com]:  https://semaphoreci.com/
+[account settings]: https://semaphoreci.com/users/edit
+[Semaphore API]:    https://semaphoreci.com/docs/api.html
+
+[jq]:  https://stedolan.github.io/jq/
+[coc]: https://en.wikipedia.org/wiki/Convention_over_configuration
 
 ## Development
 
-    $ gem build git-semaphore.gemspec
-    $ # this will generate a 'git-semaphore-x.y.z.gem' file
-    $ gem install git-semaphore-x.y.z.gem
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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](https://rubygems.org).
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome on GitHub at https://github.com/pvdb/git-semaphore. 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
-[semaphoreci.com]: https://semaphoreci.com/
-[jazor]: https://github.com/mconigliaro/jazor

data/Rakefile

@@ -1,6 +1,13 @@
 require "bundler/gem_tasks"
+require "rake/testtask"
 
-task :default => :cucumber
+task :default => :test
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
 
 task :gemspec do
   @gemspec ||= eval(File.read(Dir["*.gemspec"].first))
@@ -10,11 +17,3 @@ desc "Validate the gemspec"
 task :validate => :gemspec do
   @gemspec.validate
 end
-
-require 'cucumber'
-require 'cucumber/rake/task'
-
-Cucumber::Rake::Task.new(:features) do |t|
-  t.cucumber_opts = "features --format pretty --tags ~@wip"
-end
-task :cucumber => :features

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "git/semaphore"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start

data/bin/setup

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+rbenv install -s
+gem install bundler
+bundle install
+
+# That's all Folks!

data/exe/git-semaphore

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'git/semaphore'
+
+if __FILE__ == $0
+
+  require 'slop'
+
+  options = Slop.parse(help: true) do
+
+    on :version,  'Print the version' do
+      puts Git::Semaphore::COPYRIGHT
+      exit(0)
+    end
+
+    banner Git::Semaphore::BANNER
+
+    on :settings, 'Display the relevants settings'
+    on :browse,   'Open the project on https://semaphoreci.com/'
+
+    on :clean,    'Deletes the cached API query results'
+
+    on :projects, 'List all projects and their current status'
+    on :branches, 'List all branches for the current project'
+    on :status,   'List the build status for the current branch'
+    on :history,  'List the build history for the current branch'
+    on :rebuild,  'Rebuild last revision for the current branch'
+
+  end
+
+  app = Git::Semaphore::App.new(Git::Semaphore.auth_token, Git::Semaphore.git_repo, ENV)
+
+  if options.settings?
+    puts app.to_json
+    exit 0
+  end
+
+  if options.browse?
+    `open #{app.branch_url}`
+    exit 0
+  end
+
+  if options.clean?
+    Git::Semaphore.empty_cache_dir
+    exit 0
+  end
+
+  if options.projects?
+    puts app.projects.to_json
+    exit 0
+  end
+
+  if options.branches?
+    puts app.branches.to_json
+    exit 0
+  end
+
+  if options.status?
+    puts app.status.to_json
+    exit 0
+  end
+
+  if options.history?
+    puts app.history.to_json
+    exit 0
+  end
+
+  if options.rebuild?
+    puts app.rebuild
+    exit 0
+  end
+
+  fail "Coming soon!"
+
+end
+
+# That's all Folks!

data/git-semaphore.gemspec

@@ -1,35 +1,31 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'git-semaphore/version'
+require 'git/semaphore/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "git-semaphore"
   spec.version       = Git::Semaphore::VERSION
   spec.authors       = ["Peter Vandenberk"]
   spec.email         = ["pvandenberk@mac.com"]
-  spec.summary       = ["git integration with https://semaphoreci.com"]
-  spec.description   = ["git integration with https://semaphoreci.com"]
+
+  spec.summary       = %q{git integration with semaphoreci.com}
+  spec.description   = %q{command-line integration with semaphoreci.com for git repositories}
   spec.homepage      = "https://github.com/pvdb/git-semaphore"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency('grit')
-  spec.add_dependency('trollop')
+  spec.add_dependency "slop", "~> 3.0"
+  spec.add_dependency "grit", "~> 2.0"
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
 
-  spec.add_development_dependency('pry')
-  spec.add_development_dependency('rake')
-  spec.add_development_dependency('bundler')
-  spec.add_development_dependency('cucumber')
-  spec.add_development_dependency('rspec')
-  spec.add_development_dependency('aruba')
-  spec.add_development_dependency('methadone')
-  spec.add_development_dependency('vcr')
-  spec.add_development_dependency('webmock')
-  spec.add_development_dependency('jazor')
-  spec.add_development_dependency('json_spec')
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-rescue"
 end