README.md in valkyrie-1.1.2 vs README.md in valkyrie-1.2.0.rc1
- old
+ new
@@ -3,35 +3,45 @@
Valkyrie is a gem for enabling multiple backends for storage of files and metadata in Samvera.
[](https://circleci.com/gh/samvera-labs/valkyrie)
[](https://coveralls.io/github/samvera-labs/valkyrie?branch=master)
[](https://waffle.io/samvera-labs/valkyrie)
+[](http://rubydoc.info/github/samvera-labs/valkyrie)
+## Primary Contacts
+### Product Owner
+
+[Carolyn Cole](https://github.com/cam156)
+
+### Technical Lead
+
+[Trey Pendragon](https://github.com/tpendragon)
+
## Installation
Add this line to your application's Gemfile:
-```ruby
-gem 'valkyrie', github: 'samvera-labs/valkyrie'
```
+gem 'valkyrie'
+```
And then execute:
$ bundle
-
## Configuration
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:
+
```
# frozen_string_literal: true
require 'valkyrie'
Rails.application.config.to_prepare do
Valkyrie::MetadataAdapter.register(
@@ -48,11 +58,11 @@
Valkyrie::Storage::Disk.new(base_path: Rails.root.join("tmp", "files")),
:disk
)
Valkyrie::StorageAdapter.register(
- Valkyrie::Storage::Fedora.new(connection: ActiveFedora.fedora.connection),
+ Valkyrie::Storage::Fedora.new(connection: Ldp::Client.new("http://localhost:8988/rest")),
:fedora
)
Valkyrie::StorageAdapter.register(
@@ -67,11 +77,11 @@
* `: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, and `Valkyrie::Persistence::Solr` for storing in Solr.
+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
@@ -99,27 +109,42 @@
* `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).
## 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. Likewise, non-breaking changes to Valkyrie can be defined as code changes that do not cause any
+errors with the current shared specs.
+
+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
include Valkyrie::Resource::AccessControls
- attribute :id, Valkyrie::Types::ID.optional # Optional to allow auto-generation of IDs
attribute :title, Valkyrie::Types::Set # Sets are unordered
attribute :authors, Valkyrie::Types::Array # Arrays are ordered
end
```
+Defining resource attributes is explained in greater detail within the [Wiki](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:
@@ -151,11 +176,15 @@
# 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).
+### 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).
+
## Installing a Development environment
### Without Docker
#### External Requirements
@@ -181,11 +210,11 @@
### Starting Docker (Mac OSX)
1. `docker-machine create default`
1. `docker-machine start default`
-1. `eval "$(docker-machine env)"
+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. Run `rake db:create db:migrate` to initialize the database
1. Develop!
@@ -201,9 +230,16 @@
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.
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.
+
+## Get Help
+
+If you have any questions regarding Valkyrie you can send a message to [the
+Samvera community tech list](mailto:samvera-tech@googlegroups.com) or the `#valkyrie`
+channel in the [Samvera community Slack
+team](https://wiki.duraspace.org/pages/viewpage.action?pageId=87460391#Getintouch!-Slack).
## License
Valkyrie is available under [the Apache 2.0 license](../LICENSE).