forkreadme 0.0.2 → 0.0.3

data/.gitignore

@@ -1,2 +1,8 @@
 Gemfile.lock
+coverage
 *.gem
+test/fixtures/empty
+test/fixtures/git_repo
+test/fixtures/github_repo
+test/fixtures/github_fork
+test/fixtures/cassettes

data/README.md

@@ -1,34 +1,67 @@
-This is a command-line utility for generating READMEs for GitHub forks.
+# ForkReadme
 
-I have quite a few forks of popular repos which contain no useful indication of
-why they exist. Mostly they're hanging around waiting for a pull request to be
-merged into or rejected from the upstream repo. And since my changes are tucked
-away in feature branches, it's not immediately obvious to visitors (or me) why I
-created the fork, what I changed, and whether those changes have been merged
-upstream.
+This is a command-line utility for generating useful READMEs for GitHub forks.
 
-My solution is to replace the `README.md` in the master branch of my fork with a
-note detailing what and why.  
-This tool does that automatically.
+I have quite a few forks which contain no useful indication of why they exist.
+Mostly they're hanging around waiting for a pull request to be merged into or
+rejected from the upstream repo. And since my changes are tucked away in feature
+branches, it's not immediately obvious to visitors (including myself, six months
+later) why I created the fork, what I changed, and whether or not those changes
+have been merged upstream.
 
+My solution is to create an orphan branch containing a README explaining what's
+going on, and make that the default branch on GitHub. This little tool does the
+first part automatically.
 
-## Usage
 
-```bash
+## Installation
+
+Get it via [RubyGems] [gem]:
+
+```
 $ gem install forkreadme
-$ forkreadme generate
 ```
 
-Here's an [example of the output] [example].
+
+## Usage
+
+1. Create an empty branch with no history:
+
+   ```
+   $ git checkout --orphan forkreadme
+   $ git rm -rf .
+   ```
+
+   The `git rm` part is a bit scary, but it's just clearing the working area.  
+   Check out `git help checkout` and search for `--orphan` for more info.
+
+2. Generate the README:
+
+   ```
+   $ forkreadme > README.md
+   ```
+
+   Here's [an example] [example] of the output.
+
+3. Push it to GitHub:
+
+   ```
+   $ git add README.md
+   $ git commit -m "Add README.md"
+   $ git push origin forkreadme
+   ```
+
+4. [Change the default branch] [set-branch] on GitHub.
 
 
 ## License
 
-[Fork README] [repo] is available under the [MIT license] [license].
+ForkReadme is available under the [MIT license] [license].
 
 
 
 
-[repo]:    https://github.com/adammck/forkreadme
-[license]: https://raw.github.com/adammck/forkreadme/master/LICENSE
-[example]: https://github.com/adammck/grit
+[gem]:        https://rubygems.org/gems/forkreadme
+[example]:    https://github.com/adammck/grit#readme
+[set-branch]: https://github.com/blog/421-pick-your-default-branch
+[license]:    https://raw.github.com/adammck/forkreadme/master/LICENSE

data/Rakefile

@@ -0,0 +1,58 @@
+#!/usr/bin/env rake
+# vim: et ts=2 sw=2
+
+require "fileutils"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.pattern = "test/test_*.rb"
+end
+
+# Check fixtures before running tests.
+task :test => "fixtures:check"
+
+
+namespace :fixtures do
+  def fixture name
+    File.join File.dirname(__FILE__), "test", "fixtures", name
+  end
+
+  desc "Check for test fixtures"
+  task :check do
+    unless File.exists? fixture "empty"
+      puts "Fixtures have not been fetched yet."
+      puts "Run $(rake fixtures:fetch) first."
+      exit 1
+    end
+  end
+
+  desc "Fetch test fixtures"
+  task :fetch do
+    empty = fixture "empty"
+    unless File.exists? empty
+      %x[mkdir #{empty}]
+    end
+
+    git_repo = fixture "git_repo"
+    unless File.exists? git_repo
+      %x[git init #{git_repo}]
+    end
+
+    github_repo = fixture "github_repo"
+    unless File.exists? github_repo
+      %x[git clone git://github.com/forkreadme-test-user-1/test.git #{github_repo} &>/dev/null]
+    end
+
+    github_fork = fixture "github_fork"
+    unless File.exists? github_fork
+      %x[git clone git://github.com/forkreadme-test-user-2/test.git #{github_fork} &>/dev/null]
+    end
+  end
+
+  desc "Delete test fixtures"
+  task :flush do
+    %w[empty git_repo github_repo github_fork].each do |name|
+      FileUtils.rm_rf fixture name
+    end
+  end
+end

data/bin/forkreadme

@@ -22,7 +22,7 @@ path = ARGV.shift || "."
 
 begin
   dir = File.expand_path path, Dir.pwd
-  puts ForkReadme::Generator.new(dir, opts[:pullstatus]).readme
+  puts ForkReadme::Generator.new(dir).readme(opts[:pullstatus])
 
 rescue ForkReadme::Error => err
   $stderr.puts err

data/forkreadme.gemspec

@@ -16,6 +16,9 @@ Gem::Specification.new do |gem|
   gem.add_dependency "trollop", "~> 1.16.2"
   gem.add_dependency "octokit", "~> 1.0.2"
 
+  gem.add_development_dependency "simplecov", "~> 0.6.4"
+  gem.add_development_dependency "vcr", "~> 2.1.1"
+
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})

data/lib/forkreadme/errors.rb

@@ -11,6 +11,6 @@ module ForkReadme
   class NotGitHubRepo < Error
   end
 
-  class NotFork < Error
+  class NotGitHubFork < Error
   end
 end

data/lib/forkreadme/generator.rb

@@ -8,17 +8,16 @@ module ForkReadme
   class Generator
     include URI::REGEXP::PATTERN
 
-    def initialize path, with_images
+    def initialize path
       @path = path
-      @with_images = with_images
 
       repo_name = github_repo_name @path
       @repo = octokit.repo repo_name
       @parent = parent_of @repo
     end
 
-    def readme
-      intro + "\n\n" + (links.join "\n")
+    def readme with_images=false
+      intro + "\n\n" + (links(with_images).join "\n")
     end
 
     # Public: Returns the introduction paragraph.
@@ -27,21 +26,30 @@ module ForkReadme
       "This is a fork of #{link}, with pull requests:"
     end
 
-    # Public: Returns a paragraph summarizing the pull requests.
-    def links
+    # Public: Generate a paragraph summarizing the pull requests.
+    #
+    # with_images - Include pullstat.us images?
+    #
+    # Returns the paragraph as Markdown.
+    def links with_images
       pull_requests(@parent).select do |pull|
-        pull.head.repo.id == @repo.id
+        @repo.id == (pull.head.repo && pull.head.repo.id)
 
       end.map do |pull|
-        "* " + line_for(pull, @with_images)
+        "* " + line_for(pull, with_images)
       end
     end
 
     private
 
-    # Private: Returns a line of Markdown summarizing a pull request.
-    def line_for pull_request, with_images
-      img = if with_images
+    # Private: Generate a one-line summary of a pull request.
+    #
+    # pull_request - The Octokit pull request to be summarized.
+    # with_image   - Include a pullstat.us image?
+    #
+    # Returns the line as Markdown.
+    def line_for pull_request, with_image
+      img = if with_image
         image "Status of ##{pull_request.number}", status_image(pull_request)
       end
 
@@ -50,14 +58,14 @@ module ForkReadme
     end
 
     # Private: Returns the parent repo (as an Octokit repo) of an Octokit repo,
-    # or raises NotFork if the repo does not have a parent.
+    # or raises NotGitHubFork if the repo does not have a parent.
     def parent_of child_repo
       if child_repo.parent
         parent_repo_name = full_name child_repo.parent
         octokit.repo parent_repo_name
       else
         child_name = full_name child_repo
-        raise NotFork.new "Not a GitHub fork: #{child_name}"
+        raise NotGitHubFork.new "Not a GitHub fork: #{child_name}"
       end
     end
 
@@ -71,14 +79,6 @@ module ForkReadme
       "!" + link_to(alt_text, href)
     end
 
-    # Private: Returns an Array containing the logins of all collaborators for
-    # an Octokit repo.
-    def collaborator_logins repo
-      octokit.collabs(full_name repo).map do |user|
-        user.login
-      end
-    end
-
     # Private: Returns the URL of the status image (via pullstat.us) for an
     # Octokit pull request.
     def status_image pull_request
@@ -98,7 +98,13 @@ module ForkReadme
     # Private: Returns the full GitHub repo name (e.g. adammck/forkreadme) of a
     # Git working directory, or raises NotGitHubRepo.
     def github_repo_name path
-      clone_url = parse_url remote_url path
+      origin = remote_origin_url path
+
+      if origin == ""
+        raise NotGitHubRepo.new "No remote origin URL: #{path}"
+      end
+
+      clone_url = parse_url origin
 
       if clone_url.host.downcase != "github.com"
         raise NotGitHubRepo.new "Not a GitHub repo: #{path}"
@@ -117,9 +123,9 @@ module ForkReadme
       @ok ||= Octokit.new(:auto_traversal=>true)
     end
   
-    # Private: Returns the remote clone URL of a Git working directory, or
-    # raises NotGitRepo.
-    def remote_url path
+    # Private: Returns the remote origin URL of a Git working directory (which
+    # may be an empty string, if the repo has no origin) or raises NotGitRepo.
+    def remote_origin_url path
       unless is_working_dir path
         raise NotGitRepo.new "Not a Git repo: #{path}"
       end
@@ -150,12 +156,12 @@ module ForkReadme
 
     # Private: Returns a filename with the extension removed.
     def chop_extension filename
-      filename.sub /\.\w+$/, ""
+      filename.sub %r{\.\w+$}, ""
     end
 
     # Private: Returns a filename with the leading slash removed.
     def chop_leading_slash filename
-      filename.sub /^\//, ""
+      filename.sub %r{^/}, ""
     end
   end
 end

data/lib/forkreadme/version.rb

@@ -2,5 +2,5 @@
 # vim: et ts=2 sw=2
 
 module ForkReadme
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/fixtures/README_with_images.md

@@ -0,0 +1,5 @@
+This is a fork of [test] (https://github.com/forkreadme-test-user-1/test), with pull requests:
+
+* [Add empty GAMMA file.] (https://github.com/forkreadme-test-user-1/test/pull/3) ![Status of #3] (https://pullstat.us/forkreadme-test-user-1/test/pull/3)
+* [Add empty BETA file.] (https://github.com/forkreadme-test-user-1/test/pull/2) ![Status of #2] (https://pullstat.us/forkreadme-test-user-1/test/pull/2)
+* [Add empty ALPHA file.] (https://github.com/forkreadme-test-user-1/test/pull/1) ![Status of #1] (https://pullstat.us/forkreadme-test-user-1/test/pull/1)

data/test/fixtures/README_without_images.md

@@ -0,0 +1,5 @@
+This is a fork of [test] (https://github.com/forkreadme-test-user-1/test), with pull requests:
+
+* [Add empty GAMMA file.] (https://github.com/forkreadme-test-user-1/test/pull/3)
+* [Add empty BETA file.] (https://github.com/forkreadme-test-user-1/test/pull/2)
+* [Add empty ALPHA file.] (https://github.com/forkreadme-test-user-1/test/pull/1)

data/test/test_generator.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# vim: et ts=2 sw=2
+
+require File.expand_path(File.dirname(__FILE__) + "/test_helper.rb")
+
+describe Generator do
+  describe "Errors" do
+    it "rejects paths which are not git repos" do
+      assert_raises(NotGitRepo) do
+        Generator.new fixture("empty")
+      end
+    end
+
+    it "rejects repos which are not hosted on github" do
+      assert_raises(NotGitHubRepo) do
+        Generator.new fixture("git_repo")
+      end
+    end
+
+    it "rejects github repos which are not forks" do
+      VCR.use_cassette("github_repo") do
+        assert_raises(NotGitHubFork) do
+          Generator.new fixture("github_repo")
+        end
+      end
+    end
+  end
+
+  describe "README" do
+    it "generates a readme without images" do
+      VCR.use_cassette("github_fork") do
+        g = Generator.new fixture("github_fork")
+        assert_equal File.read(fixture("README_without_images.md")), g.readme
+      end
+    end
+
+    it "generates a readme with images" do
+      VCR.use_cassette("github_fork") do
+        g = Generator.new fixture("github_fork")
+        assert_equal File.read(fixture("README_with_images.md")), g.readme(true)
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# vim: et ts=2 sw=2
+
+require "simplecov"
+SimpleCov.start
+
+require "vcr"
+require "minitest/autorun"
+
+require "forkreadme"
+include ForkReadme
+
+VCR.configure do |c|
+  c.cassette_library_dir = "test/fixtures/cassettes"
+  c.hook_into :faraday
+end
+
+def fixture name
+  File.join File.dirname(__FILE__), "fixtures", name
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forkreadme
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-16 00:00:00.000000000 Z
+date: 2012-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trollop
@@ -43,6 +43,38 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.1
 description: 
 email:
 - adam.mckaig@gmail.com
@@ -55,12 +87,17 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- Rakefile
 - bin/forkreadme
 - forkreadme.gemspec
 - lib/forkreadme.rb
 - lib/forkreadme/errors.rb
 - lib/forkreadme/generator.rb
 - lib/forkreadme/version.rb
+- test/fixtures/README_with_images.md
+- test/fixtures/README_without_images.md
+- test/test_generator.rb
+- test/test_helper.rb
 homepage: https://github.com/adammck/forkreadme
 licenses:
 - MIT
@@ -86,4 +123,8 @@ rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Generate useful READMEs for GitHub forks
-test_files: []
+test_files:
+- test/fixtures/README_with_images.md
+- test/fixtures/README_without_images.md
+- test/test_generator.rb
+- test/test_helper.rb