README getting started text needs to be updated with instructions to create the collection types

[hardyoyo]

Descriptive summary

As part of the Collections sprint, the README needs to mention running the task to create the collection types prior to running the task to create a default admin_set (as having a collection type is a requirement for the default admin_set).

hyrax:default_collection_types:create

Needs to be added prior to the create default administrative-set step.

Also, update the wiki accordingly:
https://github.com/samvera/hyrax/wiki/Hyrax-Development-Guide#quick-start-for-hyrax-development

And we should add a bullet to the release mgmt document that says 'Make sure to update the README if the release requires any new system dependencies or startup steps.'"

@laritakr deserves all the credit for finding this issue, I just asked for help on Slack, and she came to my rescue

[hardyoyo]

also the wiki should be updated accordingly: https://github.com/samvera/hyrax/wiki/Hyrax-Development-Guide#quick-start-for-hyrax-development

[hardyoyo]

@mjgiarlo suggests adding the following: "Maybe we should add a bullet to the release mgmt document that says 'Make sure to update the README if the release requires any new system dependencies or startup steps.'"

[no-reply]

I think this is a release blocker. Please feel free to remove the label if that is wrong.

[elrayle]

If you follow the instructions in the README and use the template when you create the new app, then the collection types are created. I just ran through the steps and confirmed that they were created.

If you look in template.rb, you will see that the last line runs the script that sets up the default collection types.

If you are migrating, there are release notes that tell you to run the script manually.

I added a note to the README in the section about Creating a Hyrax-based app that list the creation of the collection types as one of the steps that the template performs.

[elrayle]

There is no need to update the Quick Start section of the Developers Guide because the engine cart script was updated to automatically create the default collection types when rake engine_cart:generate runs.

[elrayle]

@hardyoyo I'd be interested in understanding the process you took that led to the problem. If you followed the instructions, you shouldn't have run into a problem. So that says to me, the instructions could be improved to help adopters avoid pitfalls.

[elrayle]

@no-reply Everything is working when following the instructions. Perhaps we want to add a Troubleshooting section to the README. The README is long and if a user misses a step, they can end up in a weird state. @mjgiarlo as you have been the primary keeper of the README, do you want to weigh in on this?

Another common example that I see tripping up users is failing to create the default admin set. The only symptom you see is that the 'Share your work' button is missing from the Homepage and the create work buttons are missing from Dashboard -> Works.

There may be other common pitfalls that we would want to include in this section.

Doesn't seem like a blocker. @vantuyls Your thoughts on this?

[no-reply]

If everything works as is and there is appropriate documentation for creating collection types, I think we can close the ticket.

[elrayle]

@jrr Can you comment on the request for mgr doc? If you think it is also sufficient, then this can be closed.

[elrayle]

Mgr doc updated by @jrr in PR samvera/samvera.github.io#275

Closing

[hardyoyo]

I re-traced my steps, and I think I found my problem. From my notes (which are here: http://hardyoyo.thebignow.com/article/59/from-zero-to-hacking-on-hyrax note, I've updated them to fix my mistake), I typed the following to generate a new Hyrax app:

rails _5.0.6_ new awesomenameforyournewapp -m https://raw.githubusercontent.com/samvera/hyrax/v2.0.1/template.rb

The readme currently has this example:

rails _5.0.6_ new awesomenameforyournewapp -m https://raw.githubusercontent.com/samvera/hyrax/v2.1.0.beta2/template.rb

Aha! a typo! I transposed a couple of numbers in the version number, and ended up with an ancient version of the template. SMH ugh. I do think the additions to the readme files are good ones, and I thank you for that.

[elrayle]

@hardyoyo Thanks for the update. Glad to know the instructions are working.