gemstash 1.0.0.pre.1 → 1.0.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7a9b80d9f2ba68627a8d7fff3311e0fcaeca9ed
-  data.tar.gz: ea7e01d9fc2c9390ddf93f04a5623418f92408e7
+  metadata.gz: 323e0282020fd74fa61840b2492370fd1e9b4241
+  data.tar.gz: 3e3d5e4569c9e46f81fcb383f3001d01421f3cf2
 SHA512:
-  metadata.gz: d7813e9f3b7ecfa1878456519437e8191cfac94f90294dcab6778a6b5e33a268db876d60987c567bba07ba60d02b2d16a05e3ebac0713b06e2f4c374b24d6bb5
-  data.tar.gz: 64ba438731606e20c748af9b561012604ae4d700686bc1555d5de08fd5666f40a5ce26ff2ed726c91372a739d26b9468d544f925488d0e77cb42bb03a339b281
+  metadata.gz: 4132d846fbbc750db4934f61acf625bb8fd5fe96c5b9b902f48e8a0630725b6af14dc1128fdcf12f875b242fc97a035c54ed782c163fc8f70b2deb0c27b02729
+  data.tar.gz: d67634e744f569a2fc3e677c8a7e0db65dfecab5d67804fb5aacf4e49c9c5071cc9b0e8d5581816b9d118fd070819531bac077f2c9ede20d40f66a1d3741a1ce

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+## 1.0.0.pre.2 (2015-12-14)
+
+### Upgrade Notes
+
+  - If you pushed any private gems to your Gemstash instance, you will need to run: https://gist.github.com/smellsblue/53f5a6757dcc91ad10bc
+
+### Bugfixes
+
+  - Add --pre option to gemstash installation documentation ([#54](https://github.com/bundler/gemstash/pull/54), [@farukaydin](https://github.com/farukaydin))
+  - Fix docs for `gemstash authorize` ([#59](https://github.com/bundler/gemstash/pull/59), [@farukaydin](https://github.com/farukaydin))
+  - Refactoring, changed resource metadata `:gemstash_storage_version` to use `:gemstash_resource_version` ([#60](https://github.com/bundler/gemstash/pull/60), [@smellsblue](https://github.com/smellsblue))
+  - Fix migrations for utf8 on MySQL >= 5.5 ([#64](https://github.com/bundler/gemstash/pull/64), [@chriseckhardt](https://github.com/chriseckhardt))
+
+### Features
+
+  - Support MySQL as DB backend ([#52](https://github.com/bundler/gemstash/pull/52), [@pcarranza](https://github.com/pcarranza))
+  - Add start/stop output ([#58](https://github.com/bundler/gemstash/pull/58), [@farukaydin](https://github.com/farukaydin))
+  - Add `gemstash --version` ([#62](https://github.com/bundler/gemstash/pull/62), [@smellsblue](https://github.com/smellsblue))
+  - Create the CHANGELOG ([#63](https://github.com/bundler/gemstash/pull/63), [@smellsblue](https://github.com/smellsblue))
+
+## 1.0.0.pre.1 (2015-11-30)
+
+### Features
+
+  - Cache gems from multiple sources
+  - Push, yank, and unyank private gems
+  - Zero setup dependencies
+  - Optionally use Memcached for caching or PostgreSQL for the database

data/README.md

@@ -28,12 +28,14 @@ Quickstart Guide, you will be able to bundle stashed gems from public sources
 against a Gemstash server running on your machine.
 
 Install Gemstash to get started:
+
 ```
-$ gem install gemstash
+$ gem install gemstash --pre
 ```
 
 After it is installed, starting Gemstash requires no additional steps. Simply
 start the Gemstash server with the `gemstash` command:
+
 ```
 $ gemstash start
 ```
@@ -43,17 +45,24 @@ will run the server in the background by default. The server runs on port 9292.
 
 ### Bundling
 
-With the server running, you can bundle against it. Create a simple `Gemfile`
-like the following:
+With the server running, you can bundle against it. Tell Bundler that you want
+to use Gemstash to find gems from RubyGems.org:
+
+```
+$ bundle config mirror.https://rubygems.org http://localhost:9292
+```
+
+Now you can create a Gemfile and install gems through Gemstash:
+
 ```ruby
 # ./Gemfile
-source "http://localhost:9292"
+source "https://rubygems.org"
 gem "rubywarrior"
 ```
 
-The first line is important, as it will tell Bundler to use your new Gemstash
-server. The gems you include should be gems you don't yet have installed,
+The gems you include should be gems you don't yet have installed,
 otherwise Gemstash will have nothing to stash. Now bundle:
+
 ```
 $ bundle install --path .bundle
 ```
@@ -63,6 +72,7 @@ cached them for you! To prove this, you can disable your Internet connection and
 try again. The gem dependencies from https://www.rubygems.org are cached for 30
 minutes, so if you bundle again before that, you can successfully bundle without
 an Internet connection:
+
 ```
 $ # Disable your Internet first!
 $ rm -rf Gemfile.lock .bundle
@@ -73,10 +83,18 @@ $ bundle
 
 Once you've finish using your Gemstash server, you can stop it just as easily as
 you started it:
+
 ```
 $ gemstash stop
 ```
 
+You'll also want to tell Bundler that it can go back to getting gems from
+RubyGems.org directly, instead of going through Gemstash:
+
+```
+$ bundle config --delete mirror.https://rubygems.org
+```
+
 ### Under the Hood
 
 You might wonder where the gems are stored. After running the commands above,
@@ -118,6 +136,10 @@ For an anatomy of various configuration and commands, follow the links:
 * [Stop](docs/reference.md#stop)
 * [Status](docs/reference.md#status)
 * [Setup](docs/reference.md#setup)
+* [Version](docs/reference.md#version)
+
+To see what has changed in recent versions of Gemstash, see the
+[CHANGELOG](CHANGELOG.md).
 
 ## Development
 

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
+require_relative "rake/changelog.rb"
+require_relative "rake/table_of_contents.rb"
 
 RuboCop::RakeTask.new
 
@@ -9,27 +11,15 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = %w(--color)
 end
 
-task :spec => :rubocop
-task :default => :spec
+task spec: :rubocop
+task default: :spec
 
 desc "Generate Table of Contents for certain docs"
 task :toc do
-  toc_dir = File.expand_path("../tmp/", __FILE__)
-  toc = File.join(toc_dir, "gh-md-toc")
-
-  unless File.exist?(toc)
-    require "open-uri"
-    toc_contents = open("https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc", &:read)
-    Dir.mkdir(toc_dir) unless Dir.exist?(toc_dir)
-    File.write(toc, toc_contents)
-    File.chmod(0776, toc)
-  end
+  TableOfContents.new.run
+end
 
-  doc = File.expand_path("../docs/reference.md", __FILE__)
-  old_contents = File.read(doc)
-  old_contents.sub!(/\A.*?^---$/m, "---")
-  File.write(doc, old_contents)
-  toc_contents = `"#{toc}" "#{doc}"`
-  toc_contents.sub!(/Created by.*$/, "")
-  File.write(doc, "#{toc_contents}\n#{old_contents}")
+desc "Update ChangeLog based on commits in master"
+task :changelog do
+  Changelog.new.run
 end

data/docs/private_gems.md

@@ -14,7 +14,7 @@ key against your server. Instead of the key value here, use whatever key is
 generated from running the commands.
 
 In order to push a gem to your Gemstash server, you need to first create an API
-key. Utilize the `gemstash` command to create the API key:
+key. Utilize the `gemstash authorize` command to create the API key:
 ```
 $ gemstash authorize
 Your new key is: e374e237fdf5fa5718d2a21bd63dc911

data/docs/reference.md

@@ -37,6 +37,8 @@ Table of Contents
         * [--redo](#--redo)
         * [--debug](#--debug)
         * [--config-file](#--config-file-4)
+    * [Version](#version)
+      * [Usage](#usage-5)
 
 
 
@@ -182,6 +184,7 @@ Specify the API key to affect. This should be the actual key value, not a name.
 This option is required when using `--remove` but is optional otherwise. If
 adding an authorization, using this will either create or update the permissions
 for the specified API key. If missing, a new API key will always be generated.
+Note that a key can only have a maximum length of 255 chars.
 
 #### --remove
 
@@ -303,6 +306,18 @@ Specify the config file to write to. Without this option, your configuration
 will be written to `~/.gemstash/config.yml`. If you write to a custom location,
 you will need to pass the `--config-file` option to all Gemstash commands.
 
+## Version
+
+Show what version of Gemstash you are using.
+
+### Usage
+
+```
+gemstash version
+gemstash --version
+gemstash -v
+```
+
 ---
 
 Table of contents thanks to [gh-md-toc](https://github.com/ekalinin/github-markdown-toc).

data/gemstash.gemspec

@@ -40,6 +40,8 @@ you push your own private gems as well."
   end
 
   spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "citrus", "~> 3.0"
+  spec.add_development_dependency "octokit", "~> 4.2"
   spec.add_development_dependency "rack-test", "~> 0.6"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.3"

data/lib/gemstash.rb

@@ -17,6 +17,7 @@ module Gemstash
   autoload :LruReduxClient,      "gemstash/cache"
   autoload :NotAuthorizedError,  "gemstash/authorization"
   autoload :RackEnvRewriter,     "gemstash/rack_env_rewriter"
+  autoload :Resource,            "gemstash/storage"
   autoload :SpecsBuilder,        "gemstash/specs_builder"
   autoload :Storage,             "gemstash/storage"
   autoload :Upstream,            "gemstash/upstream"

data/lib/gemstash/cli.rb

@@ -67,5 +67,11 @@ module Gemstash
     def stop
       Gemstash::CLI::Stop.new(self).run
     end
+
+    desc "version", "Prints gemstash version information"
+    def version
+      say "Gemstash version #{Gemstash::VERSION}"
+    end
+    map %w(-v --version) => :version
   end
 end

data/lib/gemstash/cli/base.rb

@@ -35,7 +35,9 @@ module Gemstash
       def check_gemstash_version
         version = Gem::Version.new(Gemstash::Storage.metadata[:gemstash_version])
         return if Gem::Requirement.new("<= #{Gemstash::VERSION}").satisfied_by?(Gem::Version.new(version))
-        raise Gemstash::CLI::Error.new(@cli, "Gemstash version is too old")
+        raise Gemstash::CLI::Error.new(@cli, "Gemstash version #{Gemstash::VERSION} does not support version " \
+                                             "#{version}.\nIt appears you may have downgraded Gemstash, please " \
+                                             "install version #{version} or later.")
       end
 
       def pidfile_args

data/lib/gemstash/cli/setup.rb

@@ -77,27 +77,27 @@ module Gemstash
 
       def ask_database
         say_current_config(:db_adapter, "Current database adapter")
-        options = %w(sqlite3 postgres)
+        options = %w(sqlite3 postgres mysql)
         database = nil
 
         until database
-          database = @cli.ask "What database adapter? [SQLITE3, postgres]"
+          database = @cli.ask "What database adapter? [SQLITE3, postgres, mysql]"
           database = database.downcase
           database = "sqlite3" if database.empty?
           database = nil unless options.include?(database)
         end
 
         @config[:db_adapter] = database
-        ask_postgres_details if database == "postgres"
+        ask_database_details(database) unless database == "sqlite3"
       end
 
-      def ask_postgres_details
+      def ask_database_details(database)
         say_current_config(:db_url, "Current database url")
 
         if RUBY_PLATFORM == "java"
-          default_value = "jdbc:postgres:///gemstash"
+          default_value = "jdbc:#{database}:///gemstash"
         else
-          default_value = "postgres:///gemstash"
+          default_value = "#{database}:///gemstash"
         end
 
         url = @cli.ask "Where is the database? [#{default_value}]"

data/lib/gemstash/cli/start.rb

@@ -10,6 +10,7 @@ module Gemstash
         prepare
         setup_logging
         store_daemonized
+        @cli.say("Starting gemstash!", :green)
         Puma::CLI.new(args, Gemstash::Logging::StreamLogger.puma_events).run
       end
 

data/lib/gemstash/cli/stop.rb

@@ -9,6 +9,7 @@ module Gemstash
       def run
         prepare
         Puma::ControlCLI.new(args).run
+        @cli.say("Gemstash stopped successfully!", :green)
       end
 
     private

data/lib/gemstash/env.rb

@@ -113,7 +113,7 @@ module Gemstash
           else
             db = Sequel.connect("sqlite://#{URI.escape(db_path)}", max_connections: 1)
           end
-        when "postgres"
+        when "postgres", "mysql"
           db = Sequel.connect(config[:db_url])
         else
           raise "Unsupported DB adapter: '#{config[:db_adapter]}'"

data/lib/gemstash/gem_source/private_source.rb

@@ -71,7 +71,7 @@ module Gemstash
         gem = fetch_gem(gem_full_name)
         halt 404 unless gem.exist?(:spec)
         content_type "application/octet-stream"
-        gem.load(:spec).content(:spec)
+        gem.content(:spec)
       end
 
       def serve_actual_gem(id)
@@ -130,7 +130,6 @@ module Gemstash
       def fetch_gem(gem_full_name)
         gem = storage.resource(gem_full_name)
         halt 404 unless gem.exist?(:gem)
-        gem.load(:gem)
         halt 403, "That gem has been yanked" unless gem.properties[:indexed]
         gem
       end

data/lib/gemstash/gem_source/upstream_source.rb

@@ -118,10 +118,10 @@ module Gemstash
 
     private
 
-      def serve_cached(id, key)
-        gem = fetch_gem(id, key)
-        headers.update(gem.properties[:headers][key]) if gem.properties[:headers] && gem.properties[:headers][key]
-        gem.content(key)
+      def serve_cached(id, resource_type)
+        gem = fetch_gem(id, resource_type)
+        headers.update(gem.properties[:headers][resource_type]) if gem.property?(:headers, resource_type)
+        gem.content(resource_type)
       rescue Gemstash::WebError => e
         halt e.code
       end
@@ -142,25 +142,25 @@ module Gemstash
         @gem_fetcher ||= Gemstash::GemFetcher.new(http_client_for(upstream))
       end
 
-      def fetch_gem(id, key)
+      def fetch_gem(id, resource_type)
         gem_name = Gemstash::Upstream::GemName.new(upstream, id)
         gem_resource = storage.resource(gem_name.name)
-        if gem_resource.exist?(key)
-          fetch_local_gem(gem_name, gem_resource, key)
+        if gem_resource.exist?(resource_type)
+          fetch_local_gem(gem_name, gem_resource, resource_type)
         else
-          fetch_remote_gem(gem_name, gem_resource, key)
+          fetch_remote_gem(gem_name, gem_resource, resource_type)
         end
       end
 
-      def fetch_local_gem(gem_name, gem_resource, key)
-        log.info "Gem #{gem_name.name} exists, returning cached #{key}"
-        gem_resource.load(key)
+      def fetch_local_gem(gem_name, gem_resource, resource_type)
+        log.info "Gem #{gem_name.name} exists, returning cached #{resource_type}"
+        gem_resource
       end
 
-      def fetch_remote_gem(gem_name, gem_resource, key)
-        log.info "Gem #{gem_name.name} is not cached, fetching #{key}"
-        gem_fetcher.fetch(gem_name.id, key) do |content, properties|
-          gem_resource.save({ key => content }, headers: { key => properties })
+      def fetch_remote_gem(gem_name, gem_resource, resource_type)
+        log.info "Gem #{gem_name.name} is not cached, fetching #{resource_type}"
+        gem_fetcher.fetch(gem_name.id, resource_type) do |content, properties|
+          gem_resource.save({ resource_type => content }, headers: { resource_type => properties })
         end
       end
     end

data/lib/gemstash/migrations/01_gem_dependencies.rb

@@ -2,7 +2,7 @@ Sequel.migration do
   change do
     create_table :rubygems do
       primary_key :id
-      String :name, :size => 255, :null => false
+      String :name, :size => 191, :null => false
       DateTime :created_at, :null => false
       DateTime :updated_at, :null => false
       index [:name], :unique => true
@@ -11,10 +11,10 @@ Sequel.migration do
     create_table :versions do
       primary_key :id
       Integer :rubygem_id, :null => false
-      String :storage_id, :size => 255, :null => false
-      String :number, :size => 255, :null => false
-      String :platform, :size => 255, :null => false
-      String :full_name, :size => 255, :null => false
+      String :storage_id, :size => 191, :null => false
+      String :number, :size => 191, :null => false
+      String :platform, :size => 191, :null => false
+      String :full_name, :size => 191, :null => false
       TrueClass :indexed, :default => true, :null => false
       TrueClass :prerelease, :null => false
       DateTime :created_at, :null => false
@@ -30,8 +30,8 @@ Sequel.migration do
     create_table :dependencies do
       primary_key :id
       Integer :version_id, :null => false
-      String :rubygem_name, :size => 255, :null => false
-      String :requirements, :size => 255, :null => false
+      String :rubygem_name, :size => 191, :null => false
+      String :requirements, :size => 191, :null => false
       DateTime :created_at, :null => false
       DateTime :updated_at, :null => false
       index [:version_id]

data/lib/gemstash/migrations/02_authorizations.rb

@@ -2,8 +2,8 @@ Sequel.migration do
   change do
     create_table :authorizations do
       primary_key :id
-      String :auth_key, :size => 2056, :null => false
-      String :permissions, :size => 255, :null => false
+      String :auth_key, :size => 191, :null => false
+      String :permissions, :size => 191, :null => false
       DateTime :created_at, :null => false
       DateTime :updated_at, :null => false
       index [:auth_key], :unique => true

data/lib/gemstash/storage.rb

@@ -5,34 +5,57 @@ require "fileutils"
 require "yaml"
 
 module Gemstash
-  #:nodoc:
+  # The entry point into the storage engine for storing cached gems, specs, and
+  # private gems.
   class Storage
     extend Gemstash::Env::Helper
     VERSION = 1
 
-    # If the storage engine detects something that was stored with a newer
-    # version of the storage engine, this error will be thrown.
+    # If the storage engine detects the base cache directory was originally
+    # initialized with a newer version, this error is thrown.
     class VersionTooNew < StandardError
+      def initialize(folder, version)
+        super("Gemstash storage version #{Gemstash::Storage::VERSION} does " \
+              "not support version #{version} found at #{folder}")
+      end
     end
 
+    # This object should not be constructed directly, but instead via
+    # {for} and {#for}.
     def initialize(folder, root: true)
-      check_engine if root
       @folder = folder
+      check_storage_version if root
       FileUtils.mkpath(@folder) unless Dir.exist?(@folder)
     end
 
+    # Fetch the resource with the given +id+ within this storage.
+    #
+    # @param id [String] the id of the resource to fetch
+    # @return [Gemstash::Resource] a new resource instance from the +id+
     def resource(id)
       Resource.new(@folder, id)
     end
 
+    # Fetch a nested entry from this instance in the storage engine.
+    #
+    # @param child [String] the name of the nested entry to load
+    # @return [Gemstash::Storage] a new storage instance for the +child+
     def for(child)
       Storage.new(File.join(@folder, child), root: false)
     end
 
+    # Fetch a base entry in the storage engine.
+    #
+    # @param name [String] the name of the entry to load
+    # @return [Gemstash::Storage] a new storage instance for the +name+
     def self.for(name)
       new(gemstash_env.base_file(name))
     end
 
+    # Read the global metadata for Gemstash and the storage engine. If the
+    # metadata hasn't been stored yet, it will be created.
+    #
+    # @return [Hash] the metadata about Gemstash and the storage engine
     def self.metadata
       file = gemstash_env.base_file("metadata.yml")
 
@@ -46,10 +69,10 @@ module Gemstash
 
   private
 
-    def check_engine
+    def check_storage_version
       version = Gemstash::Storage.metadata[:storage_version]
       return if version <= Gemstash::Storage::VERSION
-      raise Gemstash::Storage::VersionTooNew, "Storage engine is out of date: #{version}"
+      raise Gemstash::Storage::VersionTooNew.new(@folder, version)
     end
 
     def path_valid?(path)
@@ -59,10 +82,25 @@ module Gemstash
     end
   end
 
-  #:nodoc:
+  # A resource within the storage engine. The resource may have 1 or more files
+  # associated with it along with a metadata Hash that is stored in a YAML file.
   class Resource
     include Gemstash::Logging
     attr_reader :name, :folder
+    VERSION = 1
+
+    # If the storage engine detects a resource was originally saved from a newer
+    # version, this error is thrown.
+    class VersionTooNew < StandardError
+      def initialize(name, folder, version)
+        super("Gemstash resource version #{Gemstash::Resource::VERSION} does " \
+              "not support version #{version} for resource #{name.inspect} " \
+              "found at #{folder}")
+      end
+    end
+
+    # This object should not be constructed directly, but instead via
+    # {Gemstash::Storage#resource}.
     def initialize(folder, name)
       @base_path = folder
       @name = name
@@ -78,6 +116,13 @@ module Gemstash
       @folder = File.join(@base_path, *trie_parents, child_folder)
     end
 
+    # When +key+ is nil, this will test if this resource exists with any
+    # content. If a +key+ is provided, this will test that the resource exists
+    # with at least the given +key+ file. The +key+ corresponds to the +content+
+    # key provided to {#save}.
+    #
+    # @param key [Symbol, nil] the key of the content to check existence
+    # @return [Boolean] true if the indicated content exists
     def exist?(key = nil)
       if key
         File.exist?(properties_filename) && File.exist?(content_filename(key))
@@ -86,6 +131,25 @@ module Gemstash
       end
     end
 
+    # Save one or more files for this resource given by the +content+ hash.
+    # Metadata properties about the file(s) may be provided in the optional
+    # +properties+ parameter. The keys in the content hash correspond to the
+    # file name for this resource, while the values will be the content stored
+    # for that key.
+    #
+    # Separate calls to save for the same resource will replace existing files,
+    # and add new ones. Properties on additional calls will be merged with
+    # existing properties.
+    #
+    # Examples:
+    #
+    #   Gemstash::Storage.for("foo").resource("bar").save(baz: "qux")
+    #   Gemstash::Storage.for("foo").resource("bar").save(baz: "one", qux: "two")
+    #   Gemstash::Storage.for("foo").resource("bar").save({ baz: "qux" }, meta: true)
+    #
+    # @param content [Hash{Symbol => String}] files to save, *must not be nil*
+    # @param properties [Hash, nil] metadata properties related to this resource
+    # @return [Gemstash::Resource] self for chaining purposes
     def save(content, properties = nil)
       content.each do |key, value|
         save_content(key, value)
@@ -95,28 +159,74 @@ module Gemstash
       self
     end
 
+    # Fetch the content for the given +key+. This will load and cache the
+    # properties and the content of the +key+. The +key+ corresponds to the
+    # +content+ key provided to {#save}.
+    #
+    # @param key [Symbol] the key of the content to load
+    # @return [String] the content stored in the +key+
     def content(key)
+      @content ||= {}
+      load(key) unless @content.include?(key)
       @content[key]
     end
 
+    # Fetch the metadata properties for this resource. The properties will be
+    # cached for future calls.
+    #
+    # @return [Hash] the metadata properties for this resource
     def properties
+      load_properties
       @properties || {}
     end
 
+    # Update the metadata properties of this resource. The +props+ will be
+    # merged with any existing properties.
+    #
+    # @param props [Hash] the properties to add
+    # @return [Gemstash::Resource] self for chaining purposes
     def update_properties(props)
-      load_properties
+      load_properties(true)
       save_properties(properties.merge(props || {}))
       self
     end
 
-    def load(key)
-      raise "Resource #{@name} has no content to load" unless exist?(key)
-      load_properties
-      @content ||= {}
-      @content[key] = read_file(content_filename(key))
-      self
+    # Check if the metadata properties includes the +keys+. The +keys+ represent
+    # a nested path in the properties to check.
+    #
+    # Examples:
+    #
+    #   resource = Gemstash::Storage.for("x").resource("y")
+    #   resource.save({ file: "content" }, foo: "one", bar: { baz: "qux" })
+    #   resource.has_property?(:foo)       # true
+    #   resource.has_property?(:bar, :baz) # true
+    #   resource.has_property?(:missing)   # false
+    #   resource.has_property?(:foo, :bar) # false
+    #
+    # @param keys [Array<Object>] one or more keys pointing to a property
+    # @return [Boolean] whether the nested keys points to a valid property
+    def property?(*keys)
+      keys.inject(node: properties, result: true) do |memo, key|
+        if memo[:result]
+          memo[:result] = memo[:node].is_a?(Hash) && memo[:node].include?(key)
+          memo[:node] = memo[:node][key] if memo[:result]
+        end
+
+        memo
+      end[:result]
     end
 
+    # Delete the content for the given +key+. If the +key+ is the last one for
+    # this resource, the metadata properties will be deleted as well. The +key+
+    # corresponds to the +content+ key provided to {#save}.
+    #
+    # The resource will be reset afterwards, clearing any cached content or
+    # properties.
+    #
+    # Does nothing if the key doesn't {#exist?}.
+    #
+    # @param key [Symbol] the key of the content to delete
+    # @return [Gemstash::Resource] self for chaining purposes
     def delete(key)
       return self unless exist?(key)
 
@@ -139,17 +249,25 @@ module Gemstash
 
   private
 
-    def load_properties
+    def load(key)
+      raise "Resource #{@name} has no #{key.inspect} content to load" unless exist?(key)
+      load_properties # Ensures storage version is checked
+      @content ||= {}
+      @content[key] = read_file(content_filename(key))
+    end
+
+    def load_properties(force = false)
+      return if @properties && !force
       return unless File.exist?(properties_filename)
-      @properties = YAML.load_file(properties_filename)
-      check_version
+      @properties = YAML.load_file(properties_filename) || {}
+      check_resource_version
     end
 
-    def check_version
-      version = @properties[:gemstash_storage_version]
-      return if version <= Gemstash::Storage::VERSION
+    def check_resource_version
+      version = @properties[:gemstash_resource_version]
+      return if version <= Gemstash::Resource::VERSION
       reset
-      raise Gemstash::Storage::VersionTooNew, "Resource was stored with a newer storage: #{version}"
+      raise Gemstash::Resource::VersionTooNew.new(name, folder, version)
     end
 
     def reset
@@ -159,8 +277,8 @@ module Gemstash
 
     def content?
       return false unless Dir.exist?(@folder)
-      entries = Dir.entries(@folder).reject {|file| file =~ /\A\.\.?\z/ }
-      !entries.empty? && entries != %w(properties.yaml)
+      entries = Dir.entries(@folder).reject {|file| file =~ /\A\.\.?\z/ || file == "properties.yaml" }
+      !entries.empty?
     end
 
     def sanitize(name)
@@ -175,7 +293,7 @@ module Gemstash
 
     def save_properties(props)
       props ||= {}
-      props = { gemstash_storage_version: Gemstash::Storage::VERSION }.merge(props)
+      props = { gemstash_resource_version: Gemstash::Resource::VERSION }.merge(props)
       store(properties_filename, props.to_yaml)
       @properties = props
     end

data/lib/gemstash/version.rb

@@ -1,4 +1,4 @@
 #:nodoc:
 module Gemstash
-  VERSION = "1.0.0.pre.1"
+  VERSION = "1.0.0.pre.2"
 end

data/rake/changelog.citrus

@@ -0,0 +1,157 @@
+# Resulting structure:
+#
+# versions[]
+#   number
+#   date
+#   description
+#   sections[]
+#     title
+#     description
+#     changes[]
+#       comment
+#       pull_requests[]
+#         number
+#         url
+#       authors[]
+#         username
+#         url
+grammar Changelog::Grammar
+  rule versions
+    (version+) {
+      def versions
+        captures[:version]
+      end
+    }
+  end
+
+  rule version
+    (version_header version_section+) {
+      def number
+        capture(:version_header).capture(:version_number).value
+      end
+
+      def date
+        capture(:version_header).capture(:date).value
+      end
+
+      def description
+        result = capture(:version_header).capture(:description)
+        result.value if result
+      end
+
+      def sections
+        captures[:version_section]
+      end
+
+      def pull_requests
+        sections.map(&:changes).flatten.map(&:pull_requests).flatten
+      end
+    }
+  end
+
+  rule version_header
+    "## " version_number:(/\d+(\.\d+)*(\.pre\.\d+)?/) " (" date:(/\d{4}-\d{2}-\d{2}/) ")\n\n"
+    description?
+  end
+
+  rule version_section
+    ("### " title:(/[^\n]*/) "\n\n" description? changes?) {
+      def title
+        capture(:title).value
+      end
+
+      def heading
+        "### #{title}\n\n#{description}"
+      end
+
+      def description
+        capture(:description).value if capture(:description)
+      end
+
+      def changes
+        if capture(:changes)
+          capture(:changes).captures[:change]
+        else
+          []
+        end
+      end
+    }
+  end
+
+  rule description
+    paragraph+
+  end
+
+  rule paragraph
+    ("  " !"- " /\w[^\n]*/ "\n")+ "\n"
+  end
+
+  rule changes
+    change+ "\n"?
+  end
+
+  rule change
+    ("  - " comment:(/[^()\n]*/) pull_requests_and_authors? "\n") {
+      def comment
+        capture(:comment).value
+      end
+
+      def pull_requests
+        pull_requests_and_authors(:pull_requests)
+      end
+
+      def authors
+        pull_requests_and_authors(:authors)
+      end
+
+    private
+
+      def pull_requests_and_authors(type)
+        return [] unless capture(:pull_requests_and_authors)
+        return [] unless capture(:pull_requests_and_authors).capture(type)
+        singular = type.to_s.sub(/s$/, "").to_sym
+        capture(:pull_requests_and_authors).capture(type).capture(singular) || []
+      end
+    }
+  end
+
+  rule pull_requests_and_authors
+    "(" pull_requests ", " authors ")"
+  end
+
+  rule pull_requests
+    pull_request (", " pull_request)*
+  end
+
+  rule pull_request
+    ("[#" number:(/\d+/) "](" github_url ")") {
+      def number
+        capture(:number).value
+      end
+
+      def url
+        capture(:github_url).value
+      end
+    }
+  end
+
+  rule authors
+    author (", " author)*
+  end
+
+  rule author
+    ("[@" username:(/\w+/) "](" github_url ")") {
+      def username
+        capture(:username).value
+      end
+
+      def url
+        capture(:github_url).value
+      end
+    }
+  end
+
+  rule github_url
+    "https://github.com" path:(/\/\w*/)*
+  end
+end

data/rake/changelog.rb

@@ -0,0 +1,201 @@
+require "set"
+
+# Helper class for updating CHANGELOG.md
+class Changelog
+  attr_reader :changelog_file, :parsed, :parsed_current_version, :parsed_last_version, :missing_pull_requests
+
+  def initialize
+    @changelog_file = File.expand_path("../../CHANGELOG.md", __FILE__)
+  end
+
+  def run
+    ensure_new_version_specified
+    parse_changelog
+    fetch_missing_pull_requests
+    update_changelog
+  end
+
+  def ensure_new_version_specified
+    tags = `git tag -l`
+    return unless tags.include? Changelog.current_version
+    Changelog.error("Please update lib/gemstash/version.rb with the new version first!")
+  end
+
+  def parse_changelog
+    require "citrus"
+    Citrus.load(File.expand_path("../changelog.citrus", __FILE__))
+    @parsed = Changelog::Grammar.parse(File.read(changelog_file))
+    @parsed_current_version = @parsed.versions.find {|version| version.number == Changelog.current_version }
+
+    if @parsed_current_version
+      index = @parsed.versions.index(@parsed_current_version)
+      @parsed_last_version = @parsed.versions[index + 1]
+    else
+      @parsed_last_version = @parsed.versions.first
+    end
+  end
+
+  def last_version
+    @last_version ||= begin
+      version = parsed_last_version.number
+
+      unless version =~ /\A\d+(\.\d+)*(\.pre\.\d+)?\z/
+        error("Invalid last version: #{version}, instead use something like 1.1.0, or 1.1.0.pre.2")
+      end
+
+      version
+    end
+  end
+
+  def octokit
+    @octokit ||= begin
+      require "octokit"
+      token_path = File.expand_path("../../.rake_github_token", __FILE__)
+
+      if File.exist?(token_path)
+        options = { access_token: File.read(token_path).strip }
+      else
+        puts "\e[31mWARNING:\e[0m You do not have a GitHub OAuth token configured"
+        puts "Please generate one at: https://github.com/settings/tokens"
+        puts "And store it at: #{token_path}"
+        puts "Otherwise you might hit rate limits while running this"
+        print "Continue without token? [yes/no] "
+        abort("Please create your token and retry") unless STDIN.gets.strip.downcase == "yes"
+        options = {}
+      end
+
+      client = Octokit::Client.new(options)
+      client.auto_paginate = true
+      client
+    end
+  end
+
+  def fetch_missing_pull_requests
+    @missing_pull_requests = missing_pull_request_numbers.map {|pr| fetch_pull_request(pr) }
+  end
+
+  def fetch_pull_request(number)
+    puts "Fetching pull request ##{number}"
+    octokit.pull_request("bundler/gemstash", number)
+  end
+
+  def missing_pull_request_numbers
+    @missing_pull_request_numbers ||= begin
+      commits = `git log --oneline HEAD ^v#{last_version} --grep "^Merge pull request"`.split("\n")
+      pull_requests = commits.map {|commit| commit[/Merge pull request #(\d+)/, 1].to_i }
+      documented = Set.new
+
+      if parsed_current_version
+        parsed_current_version.pull_requests.each do |pr|
+          documented << pr.number.to_i
+        end
+      end
+
+      pull_requests.sort.reject {|pr| documented.include?(pr) }
+    end
+  end
+
+  def update_changelog
+    return if missing_pull_requests.empty?
+
+    File.open(changelog_file, "w") do |file|
+      begin
+        write_current_version(file)
+      ensure
+        parsed.versions.each do |version|
+          next if version == parsed_current_version
+          file.write version.value
+        end
+      end
+    end
+  end
+
+  def write_current_version(file)
+    pull_requests_by_section = missing_pull_requests.group_by {|pr| section_for(pr) }
+    file.puts "## #{Changelog.current_version} (#{current_date})"
+    file.puts
+
+    if parsed_current_version
+      file.puts parsed_current_version.description if parsed_current_version.description
+
+      parsed_current_version.sections.each do |section|
+        if pull_requests_by_section[section.title].to_a.empty?
+          file.write section.value
+        else
+          file.write section.heading
+          section.changes.each {|change| file.write change.value }
+          write_pull_requests(file, pull_requests_by_section[section.title])
+          file.puts
+          pull_requests_by_section.delete(section.title)
+        end
+      end
+    end
+
+    pull_requests_by_section.keys.sort.each do |section_title|
+      file.puts "### #{section_title}"
+      file.puts
+      write_pull_requests(file, pull_requests_by_section[section_title])
+      file.puts
+    end
+  end
+
+  def section_for(pull_request)
+    puts "Fetching issue for ##{pull_request.number}"
+    issue = pull_request.rels[:issue].get.data
+    labels = issue.labels.map(&:name)
+
+    if labels.include?("bug")
+      "Bugfixes"
+    elsif labels.include?("enhancement")
+      "Features"
+    else
+      "Changes"
+    end
+  end
+
+  def write_pull_requests(file, pull_requests)
+    pull_requests.each do |pr|
+      puts "Fetching commits for ##{pr.number}"
+      commits = pr.rels[:commits].get.data
+      authors = commits.map {|commit| author_link(commit) }.uniq
+      file.puts "  - #{pr.title} ([##{pr.number}](#{pr.html_url}), #{authors.join(", ")})"
+    end
+  end
+
+  def author_link(commit)
+    @author_links ||= {}
+    author = commit.author
+
+    if author
+      "[@#{author.login}](#{author.html_url})"
+    elsif @author_links[commit.commit.author.name]
+      @author_links[commit.commit.author.name]
+    else
+      puts "Cannot find GitHub link for author: #{commit.commit.author.name}"
+      print "What is their GitHub username? "
+      username = STDIN.gets.strip
+      @author_links[commit.commit.author.name] = "[@#{username}](https://github.com/#{username})"
+    end
+  end
+
+  def current_date
+    @current_date ||= Time.now.strftime("%Y-%m-%d")
+  end
+
+  def self.error(msg)
+    STDERR.puts(msg)
+    exit(false)
+  end
+
+  def self.current_version
+    @current_version ||= begin
+      require_relative "../lib/gemstash/version.rb"
+
+      unless Gemstash::VERSION =~ /\A\d+(\.\d+)*(\.pre\.\d+)?\z/
+        error("Invalid version: #{Gemstash::VERSION}, instead use something like 1.1.0, or 1.1.0.pre.2")
+      end
+
+      Gemstash::VERSION
+    end
+  end
+end

data/rake/table_of_contents.rb

@@ -0,0 +1,36 @@
+require "pathname"
+
+# Helper class for generating the table of contents in markdown files.
+class TableOfContents
+  attr_reader :toc_dir, :toc, :docs_dir
+
+  def initialize
+    @toc_dir = Pathname.new(File.expand_path("../../tmp", __FILE__))
+    @toc = @toc_dir.join("gh-md-toc")
+    @docs_dir = Pathname.new(File.expand_path("../../docs", __FILE__))
+  end
+
+  def run
+    cache_toc_script
+    update_toc("reference.md")
+  end
+
+  def update_toc(doc)
+    doc = docs_dir.join(doc)
+    old_contents = File.read(doc)
+    old_contents.sub!(/\A.*?^---$/m, "---")
+    File.write(doc, old_contents)
+    toc_contents = `"#{toc}" "#{doc}"`
+    toc_contents.sub!(/Created by.*$/, "")
+    File.write(doc, "#{toc_contents}\n#{old_contents}")
+  end
+
+  def cache_toc_script
+    return if toc.exist?
+    require "open-uri"
+    toc_contents = open("https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc", &:read)
+    Dir.mkdir(toc_dir) unless toc_dir.exist?
+    File.write(toc, toc_contents)
+    File.chmod(0776, toc)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gemstash
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.1
+  version: 1.0.0.pre.2
 platform: ruby
 authors:
 - Andre Arko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-11-30 00:00:00.000000000 Z
+date: 2015-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dalli
@@ -150,6 +150,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: citrus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -222,6 +250,7 @@ files:
 - ".rubocop-relax.yml"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -279,6 +308,9 @@ files:
 - lib/gemstash/upstream.rb
 - lib/gemstash/version.rb
 - lib/gemstash/web.rb
+- rake/changelog.citrus
+- rake/changelog.rb
+- rake/table_of_contents.rb
 homepage: https://github.com/bundler/gemstash
 licenses:
 - MIT