meteor/meteor — pull request #3375 by ekatek (2014-12-27 01:01:42+00:00)
Title: upload README files to Isobuild; change package skeleton

This commit is based on the following design document:
https://mdg.hackpad.com/Creating-and-Updating-Docs-0ZyyDcSZDxp,
and some other stuff from here: https://mdg.hackpad.com/Meteor-Long-Description-wGZ1vIOwVlF.

It does the following:

- Allow the user to specify package documentation in Package.Describe.
We will take the README.md file by default, to make the transition easier.
Users can specify ‘documentation: null’ to not submit a README.md

- From that documentation, extract the section between the first and second header
to use as the long form description for the package.

- Upload the documentation to the server at publish-time. Allow metadata changes with ‘publish —update’.

- Change the default package skeleton to include the README.md file.
Also, changes the skeleton to have fewer useless placeholders in Package.describe values.

- Fix a minor bug where Git did not show up when running ‘meteor show’ on local packages.

A note on ‘documentation: null’ and blank documentation — we don’t let maintainers upload
blank README.md files, because we want to encourage people to fill them out. (Instead,
we allow a ‘documentation: null’ as an override) This is a UX issue! It is not a technical thing.

Right now, when ‘documentation: null’, Meteor interprets that to mean ‘upload a blank README’*.
Why? Well, the alternative, is to allow the user to just remove the documentation documentation
field from the version record. To do that, we need a ‘removeReadme’ method on Troposphere.

That’s easy, but I think it is wrong:

- In the future, we want all package versions to have a README.md.
They are mostly optional right now because we want to make this transition painless for our users.

- This means that we want to move the server towards a world where records have READMEs.
Allowing that field to be removed, post-factum, moves us say from that world. It also keeps
alive bad abstractions (look at Git if there is no readme) and makes our lives slightly harder
to reason about (absolutes like ‘always uploads a readme after this version of Meteor’
and ‘always has a README’ are easier to deal with).

- Clearly, uploading a blank is a hack. With any hack, it is important to think about
when we will eliminate it. In this case, it is a hack around the UX. This is, for example,
because the UX allows you to not have documentation in the first place. We will almost certainly
think about this again when we deal with the new project control file. Similarly, the UX does not
allow you to upload blank documentation yourself. That’s because of the package skeleton and various
UX issues in package creation that, once again, will be re-examined with project control files.

- If, later, if turns out that I am wrong, this hack is confined to the tool and uses APIs that
we don’t intend to change (too much). So, removing it and putting in a Troposphere method is cheap.

- Making a method on Troposphere is less of a hack. It could stay that way forever.
But I don’t think that it will — instead, we will come to a world where we need to
deprecate that method, and move towards non-optional documentation and it is a lot harder to do.

So, that’s why I did it. But it is kind of crazy, and not as smooth as I like my
abstractions and abstraction seams to be. A second opinion would be greatly appreciated.

*: this is something we can optimize to be cheap in the far future, if we care.

Conflicts:
tools/commands-packages-query.js