README.md in valkyrie-1.7.1 vs README.md in valkyrie-2.0.0.RC1
- old
+ new
@@ -2,34 +2,27 @@
Valkyrie is a gem for enabling multiple backends for storage of files and metadata in Samvera.
-Code: [](http://badge.fury.io/rb/valkyrie)
-[](https://circleci.com/gh/samvera/valkyrie)
-
+[](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)
-Docs: [](./CONTRIBUTING.md)
-[](./LICENSE)
-[](http://rubydoc.info/gems/valkyrie)
-
-Jump in: [](http://slack.samvera.org/)
-
## Primary Contacts
### Product Owner
-[Katherine Lynch](https://github.com/kelynch)
+[Carolyn Cole](https://github.com/cam156)
+
### Technical Lead
+
[Trey Pendragon](https://github.com/tpendragon)
-## Help
+## Installation
-The Samvera community is here to help. Please see our [support guide](./SUPPORT.md).
-
-## Getting Started
-
Add this line to your application's Gemfile:
```
gem 'valkyrie'
```
@@ -42,10 +35,11 @@
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:
```
@@ -85,30 +79,20 @@
* `: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
@@ -127,16 +111,30 @@
* `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 [Persistence Wiki
-page](https://github.com/samvera/valkyrie/wiki/Persistence).
+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. 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
@@ -151,12 +149,11 @@
```
attribute :authors, Valkyrie::Types::Array.meta(ordered: true)
```
-Defining resource attributes is explained in greater detail on the [Using Types Wiki
-page](https://github.com/samvera/valkyrie/wiki/Using-Types).
+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:
@@ -170,10 +167,11 @@
```
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
@@ -188,101 +186,81 @@
# load all MyModel objects
Valkyrie.config.metadata_adapter.query_service.find_all_of_model(model: MyModel)
```
-The Wiki documents the usage of [Queries](https://github.com/samvera/valkyrie/wiki/Queries),
-[Persistence](https://github.com/samvera/valkyrie/wiki/Persistence), and
-[ChangeSets and Dirty Tracking](https://github.com/samvera/valkyrie/wiki/ChangeSets-and-Dirty-Tracking).
+The usage of `ChangeSets` in writing data are further documented [here](https://github.com/samvera-labs/valkyrie/wiki/ChangeSets-and-Dirty-Tracking).
-### 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/valkyrie/wiki/Optimistic-Locking).
+### 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).
-### 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.
+## Installing a Development environment
-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.
+### Without Docker
-Using the shared specs in your own models is described in more detail on the [Shared Specs Wiki
-page](https://github.com/samvera/valkyrie/wiki/Shared-Specs).
+#### External Requirements
+* PostgreSQL with the uuid-ossp extension.
+ * Note: Enabling uuid-ossp requires database superuser privileges.
+ * From `psql`: `alter user [username] with superuser;`
-### 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.:
+#### 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`
- ```
- 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)
+
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.
-### Without Docker
+## 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)
+ ```
-#### External Requirements
-* PostgreSQL with the uuid-ossp extension.
- * Note: Enabling uuid-ossp requires database superuser privileges.
- * From `psql`: `alter user [username] with superuser;`
+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.
-#### 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`
+## Get Help
-## Acknowledgments
+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).
-This software has been developed by and is brought to you by the Samvera community. Learn more at the
-[Samvera website](http://samvera.org/).
+## License
-
+Valkyrie is available under [the Apache 2.0 license](../LICENSE).
+
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/samvera/valkyrie/.
+Bug reports and pull requests are welcome on GitHub at https://github.com/samvera-labs/valkyrie/.