Update the generated README

[jimmynotjim]

Update the generated README with dependencies and installation instructions

Additions

None

Removals

None

Changes

• utilizes a README template for known content (borrowing from cfgov-refresh)
• grabs the OSPT README for everything from configuration down
• combines the two for a SUPER README

  Testing

• fetch and run npm link
• run mocha
• check /test/temp/README.md for new SUPER README content

  Review

• @contolini
• @ascott1
• @Scotchester
• @KimberlyMunoz
• @himedlooff

  Preview

Notes

• Open to suggestions for the dependencies and instructions. These just seemed like a good starting place
• Fixes #37

[Scotchester]

I'd like to add this section (or something like it) that I like from a slightly older version of the owning-a-home README:

### Developing

When first setting up this project, and each time you fetch from upstream,
install project dependencies with npm and run `grunt` to build everything:

    npm install
    grunt

The important part being the reminder to run those two commands every time you merge in changes from elsewhere, in case any dependencies changed. They write this a little bit different now (they have a whole Workflow section), but that's the gist I think we should mention.

[jimmynotjim]

@Scotchester should that really go under ## Usage? This brings up a point that we could fill out a lot more of these sections. Now I'm wondering if we should ditch the code that grabs the OSPT README and keep a complete README template in the generator.

[Scotchester]

Mmm, yeah, I didn't realize there was a Usage section lower in the OSPT README.

I like the idea of still pulling in (most of the) OSPT README, so that the recommendations here don't drift too far from it. But it is a bit of an annoying. I don't know, I'm on the fence.

[jimmynotjim]

As much as I'd like to be able to rely on the OSPT README, it's going to become uber complicated replacing different sections with regexes, especially if the OSPT one is updated in an unexpected way.

I think we'd be better off duplicating the generic sections and filling in the ones we feel appropriate in the template here, then manually updating it when the OSPT one is updated. There's zero risk of something going haywire that way.

[Scotchester]

I think you're probably right.

[Scotchester]

@contolini and @ascott1 opinions on this would be helpful.

[contolini]

:+1:

We should start thinking about a more maintainable, non-regex OSPT solution.

Maybe we can modify the readme to include nonintrusive template delimiters? For example, we could add HTML comments to mark the start and end of each section. They'd be invisible when the readme is viewed through GitHub but when working with it programatically, we could use them to easily replace chunks of content.

[jimmynotjim]

@contolini how would we change that from this side? It'd still require a regex to capture the area between the comments right?

@all If we're going to maintain our own README here for the time being, does anyone have recommendations on other real content that should be filled in?

[contolini]

@jimmynotjim It would still require regex on our end, but it'd be much more explicit (replace everything between <!-- start-usage --> and <!-- end-usage --> with XYZ). We would add the tags to the OSPT repo. The goal would be to avoid having to maintain two versions of the readme.

For now, I think your SUPER README strategy is a good solution but if things start getting messy we should consider alternate strategies like the one above.

[jimmynotjim]

It's already getting messy with @Scotchester's recommended update to ## Usage. Should we shelve this PR for now and concentrate on making the OSPT README more extensible first?

[contolini]

@jimmynotjim @Scotchester Here's the readme with each section wrapped in HTML comments. The comments are invisible in the rendered markdown but they do add visual clutter to the raw markdown.

I'm on the fence. It would make the readme a lot easier to deal with programatically, but it's fugly when you look at the readme's source.

[jimmynotjim]

I don't think it's terrible, but it's definitely not what I'd want to use in a non-generated project. I'm really starting to think keeping a unique README specific to CF projects is going to be the cleanest and easiest to maintain solution. Especially since most of the sections could be completed with real content and utilizing template tags would allow customization.

[contolini]

Cool, keeping a CF-specific readme makes sense. The OSPT one is incredibly verbose so having a pared down version would be nice.

[Scotchester]

Where did we leave off, here? Is this ready for merging or needs more work still?

[jimmynotjim]

More work, I'll finish this up later today or first thing tomorrow.

[Scotchester]

Bump.

[jimmynotjim]

Boy did I lose track of this. I'll find some time tomorrow to get this up to date.

[Scotchester]

Merge conflict.

[jimmynotjim]

I'll worry about the conflict once we're sure on the README. Is there anything else we want to add to that now or should we go with what we have and handle updates in future PRs?

[Scotchester]

One final comment: Please wrap lines at 80 characters, preferring breaks on periods or commas, where practical.

[Scotchester]

Looks good, but any idea why the Travis build failed this time? Seems it tried to clone the add-cf-readme branch (which is the name of your branch) but from the upstream repo (which doesn't have that branch).

[jimmynotjim]

I accidentally pushed to the upstream repo last week instead of pushing to my personal branch, that's why the update never showed up here. Any idea how to get travis to look at this branch again?

[Scotchester]

No idea. I don't think it really matters. Mergin'!

[Scotchester]

Wait, sorry, got conflicts now.

[jimmynotjim]

What in the world? No idea why, nothing new has been merged. I'll figure this out tomorrow morning and update.

[jimmynotjim]

@Scotchester Rebased with master and all fixed. Must have been because I opened this so long ago.