README.md in valkyrie-1.5.0.RC1 vs README.md in valkyrie-1.5.0.RC2

- old
+ new

@@ -16,15 +16,13 @@ Jump in: [![Slack Status](http://slack.samvera.org/badge.svg)](http://slack.samvera.org/) ## Primary Contacts ### Product Owner - [Carolyn Cole](https://github.com/cam156) ### Technical Lead - [Trey Pendragon](https://github.com/tpendragon) ## Help The Samvera community is here to help. Please see our [support guide](./SUPPORT.md). @@ -45,11 +43,10 @@ Valkyrie is configured in two places: an initializer that registers the persistence options and a YAML configuration file that sets which options are used by default in which environments. ### Sample initializer: `config/initializers/valkyrie.rb`: - Here is a sample initializer that registers a couple adapters and storage adapters, in each case linking an instance with a short name that can be used to refer to it in your application: ``` @@ -89,31 +86,30 @@ * `:memory` which stores metadata in an in-memory cache (this cache is not persistent, so it is only appropriate for testing) Other adapter options include `Valkyrie::Persistence::BufferedPersister` for buffering in memory before bulk updating another persister, `Valkyrie::Persistence::CompositePersister` for storing in more than one adapter -at once, `Valkyrie::Persistence::Solr` for storing in Solr, and `Valkyrie::Persistence::Fedora` for storing in Fedora. +at once, `Valkyrie::Persistence::Solr` for storing in Solr, and `Valkyrie::Persistence::Fedora` for storing +in Fedora. The initializer also registers three `Valkyrie::StorageAdapter` instances for storing files: * `:disk` which stores files on disk * `:fedora` which stores files in Fedora * `:memory` which stores files in an in-memory cache (again, not persistent, so this is only appropriate for testing) ### Sample configuration with custom `Valkyrie.config.resource_class_resolver`: - ``` require 'valkyrie' Rails.application.config.to_prepare do Valkyrie.config.resource_class_resolver = lambda do |resource_klass_name| # Do complicated lookup based on the string end end ``` ### Sample configuration: `config/valkyrie.yml`: - A sample configuration file that configures your application to use different adapters: ``` development: metadata_adapter: postgres @@ -132,30 +128,16 @@ * `metadata_adapter` is the store where Valkyrie will put the metadata * `storage_adapter` is the store where Valkyrie will put the files The values are the short names used in your initializer. -Further details can be found on the [the Wiki](https://github.com/samvera-labs/valkyrie/wiki/Persistence). +Further details can be found on the [Persistence Wiki +page](https://github.com/samvera-labs/valkyrie/wiki/Persistence). ## Usage -### The Public API - -Valkyrie's public API is defined by the shared specs that are used to test each of its core classes. -This include change sets, resources, persisters, adapters, and queries. When creating your own kinds of -these kinds of classes, you should use these shared specs to test your classes for conformance to -Valkyrie's API. - -When breaking changes are introduced, necessitating a major version change, the shared specs will reflect -this. When new features are added and a minor version is released there will be no change to the existing shared -specs, but there may be new ones. These new shared specs will fail in your -application if you have custom adapters, but your application will still work. - -Using the shared specs in your own models is described in more [detail](https://github.com/samvera-labs/valkyrie/wiki/Shared-Specs). - ### Define a Custom Work - Define a custom work class: ``` # frozen_string_literal: true class MyModel < Valkyrie::Resource @@ -170,11 +152,12 @@ ``` attribute :authors, Valkyrie::Types::Array.meta(ordered: true) ``` -Defining resource attributes is explained in greater detail within the [Wiki](https://github.com/samvera-labs/valkyrie/wiki/Using-Types). +Defining resource attributes is explained in greater detail on the [Using Types Wiki +page](https://github.com/samvera-labs/valkyrie/wiki/Using-Types). #### Work Types Generator To create a custom Valkyrie model in your application, you can use the Rails generator. For example, to generate a model named `FooBar` with an unordered `title` field and an ordered `member_ids` field: @@ -188,11 +171,10 @@ ``` rails generate valkyrie:resource Foo/Bar title member_ids:array ``` ### Read and Write Data - ``` # initialize a metadata adapter adapter = Valkyrie::MetadataAdapter.find(:postgres) # create an object @@ -207,69 +189,94 @@ # load all MyModel objects Valkyrie.config.metadata_adapter.query_service.find_all_of_model(model: MyModel) ``` -The usage of `ChangeSets` in writing data are further documented [here](https://github.com/samvera-labs/valkyrie/wiki/ChangeSets-and-Dirty-Tracking). +The Wiki documents the usage of [Queries](https://github.com/samvera-labs/valkyrie/wiki/Queries), +[Persistence](https://github.com/samvera-labs/valkyrie/wiki/Persistence), and +[ChangeSets and Dirty Tracking](https://github.com/samvera-labs/valkyrie/wiki/ChangeSets-and-Dirty-Tracking). -### Concurrency Support (Optimistic Locking) -By default, it is assumed that a Valkyrie repository implementation shall use a solution supporting concurrent updates for resources (multiple resources can be updated simultaneously using a Gem such as [Sidekiq](https://github.com/mperham/sidekiq)). In order to handle the possibility of multiple updates applied to the same resource corrupting data, Valkyrie supports optimistic locking. For further details, please reference the [overview of optimistic locking for Valkyrie resources](https://github.com/samvera-labs/valkyrie/wiki/Optimistic-Locking). +### Concurrency Support +A Valkyrie repository may have concurrent updates, for example, from a load-balanced Rails application, or +from multiple [Sidekiq](https://github.com/mperham/sidekiq) background workers). In order to prevent multiple +simultaneous updates applied to the same resource from losing or corrupting data, Valkyrie supports optimistic +locking. How to use optimistic locking with Valkyrie is documented on the [Optimistic Locking Wiki +page](https://github.com/samvera-labs/valkyrie/wiki/Optimistic-Locking). -## Installing a Development environment +### The Public API +Valkyrie's public API is defined by the shared specs that are used to test each of its core classes. +This include change sets, resources, persisters, adapters, and queries. When creating your own kinds of +these kinds of classes, you should use these shared specs to test your classes for conformance to +Valkyrie's API. -### Without Docker +When breaking changes are introduced, necessitating a major version change, the shared specs will reflect +this. When new features are added and a minor version is released there will be no change to the existing +shared specs, but there may be new ones. These new shared specs will fail in your application if you have +custom adapters, but your application will still work. -#### External Requirements -* PostgreSQL with the uuid-ossp extension. - * Note: Enabling uuid-ossp requires database superuser privileges. - * From `psql`: `alter user [username] with superuser;` +Using the shared specs in your own models is described in more detail on the [Shared Specs Wiki +page](https://github.com/samvera-labs/valkyrie/wiki/Shared-Specs). -#### To run the test suite -1. Start Solr and Fedora servers for testing with `rake server:test` -1. Run `rake db:create` (First time only) -1. Run `rake db:migrate` +### Fedora 5 Compatibility +When configuring your adapter, include the `fedora_version` parameter in your metadata or storage adapter +config. If Fedora requires auth, you can also include that in the URL, e.g.: + ``` + Valkyrie::Storage::Fedora.new( + connection: Ldp::Client.new("http://fedoraAdmin:fedoraAdmin@localhost:8988/rest"), + fedora_version: 5 + ) + ``` + +## Installing a Development environment + ### With Docker +The development and test stacks use fully contained virtual volumes and bind all services to different ports, +so they can be running at the same time without issue. #### External Requirements * [Docker](https://store.docker.com/search?offering=community&type=edition) version >= 17.09.0 -* -### Dependency Setup (Mac OSX) +### Dependency Setup (Mac OSX) 1. `brew install docker` 1. `brew install docker-machine` 1. `brew install docker-compose` ### Starting Docker (Mac OSX) - 1. `docker-machine create default` 1. `docker-machine start default` 1. `eval "$(docker-machine env)"` #### Starting the development mode dependencies -1. Start Solr, Fedora, and PostgreSQL with `rake docker:dev:daemon` (or `rake docker:dev:up` in a separate shell to run them in the foreground) +1. Start Solr, Fedora, and PostgreSQL with `rake docker:dev:daemon` (or `rake docker:dev:up` in a separate + shell to run them in the foreground) 1. Run `rake db:create db:migrate` to initialize the database 1. Develop! 1. Run `rake docker:dev:down` to stop the server stack * Development servers maintain data between runs. To clean them out, run `rake docker:dev:clean` #### To run the test suite with all dependencies in one go 1. `rake docker:spec` #### To run the test suite manually -1. Start Solr, Fedora, and PostgreSQL with `rake docker:test:daemon` (or `rake docker:test:up` in a separate shell to run them in the foreground) +1. Start Solr, Fedora, and PostgreSQL with `rake docker:test:daemon` (or `rake docker:test:up` in a separate + shell to run them in the foreground) 1. Run `rake db:create db:migrate` to initialize the database 1. Run the gem's RSpec test suite with `rspec spec` or `rake` 1. Run `rake docker:test:down` to stop the server stack * The test stack cleans up after itself on exit. -## Fedora 5 Compatibility -When configuring your adapter, include the `fedora_version` parameter in your metadata or storage adapter config. If Fedora requires auth, you can also include that in the URL, e.g.: - ``` - Valkyrie::Storage::Fedora.new(connection: Ldp::Client.new("http://fedoraAdmin:fedoraAdmin@localhost:8988/rest"), fedora_version: 5) - ``` +### Without Docker -The development and test stacks use fully contained virtual volumes and bind all services to different ports, so they can be running at the same time without issue. +#### External Requirements +* PostgreSQL with the uuid-ossp extension. + * Note: Enabling uuid-ossp requires database superuser privileges. + * From `psql`: `alter user [username] with superuser;` + +#### To run the test suite +1. Start Solr and Fedora servers for testing with `rake server:test` +1. Run `rake db:create` (First time only) +1. Run `rake db:migrate` ## Acknowledgments This software has been developed by and is brought to you by the Samvera community. Learn more at the [Samvera website](http://samvera.org/).