upload README.md files to the server and view the excerpt in meteor show

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
and was code reviewed here: meteor#3375

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.

There is more discussion and code review in: meteor#3375

Author: ekatek

meteor

@@ -1,10 +1,6 @@
 #!/bin/bash
 
-<<<<<<< HEAD
-BUNDLE_VERSION=0.3.82
-=======
-BUNDLE_VERSION=0.3.76
->>>>>>> d1d1353... completely rewrite of ‘meteor show’; some changes to ‘meteor search’.
+BUNDLE_VERSION=0.3.83
 
 # OS Check. Put here because here is where we download the precompiled
 # bundles that are arch specific.

scripts/dev-bundle-tool-package.js

@@ -34,6 +34,10 @@ var packageJson = {
     "http-proxy": "1.6.0",
     "wordwrap": "0.0.2",
     "moment": "2.8.4",
+    // XXX: When we update this, see if it fixes this Github issue:
+    // https://github.com/jgm/CommonMark/issues/276 . If it does, remove the
+    // workaround from the tool.
+    "commonmark": "0.15.0",
     // XXX We ought to be able to get this from the copy in js-analyze rather
     // than in the dev bundle.)
     esprima: "1.2.2",

tools/catalog-local.js

@@ -308,6 +308,7 @@ _.extend(LocalCatalog.prototype, {
             version: packageSource.version,
             publishedBy: null,
             description: packageSource.metadata.summary,
+            git: packageSource.metadata.git,
             dependencies: packageSource.getDependencyMetadata(),
             source: null,
             lastUpdated: null,

tools/commands-packages-query.js

@@ -259,7 +259,8 @@ _.extend(PkgExports.prototype, {
 // the details of printing their data to the screen.
 //
 // A query class has:
-//  - data: an object representing the data it has collected in response to the query.
+//  - data: an object representing the data it has collected in response to the
+//  - query.
 //  - a print method, that take options as an argument and prints the results to
 //    the terminal.
 
@@ -268,7 +269,6 @@ _.extend(PkgExports.prototype, {
 // packages, it has to interact with the projectContext.
 //
 // The constructor takes in the following options:
-
 //   - metaRecord: (mandatory) the meta-record for this package from the Packages
 //     collection.
 //   - projectContext: (mandatory) a projectContext that we can use to look up
@@ -466,9 +466,15 @@ _.extend(PackageQuery.prototype, {
     if (local) {
       data["defaultVersion"] = local;
     } else {
-      var mainRecord = catalog.official.getLatestMainlineVersion(self.name);
-      if (mainRecord) {
-        data["defaultVersion"] = self._getOfficialVersion(mainRecord);
+      var mainlineRecord = catalog.official.getLatestMainlineVersion(self.name);
+      if (mainlineRecord) {
+        var pkgExports = new PkgExports(mainlineRecord.exports);
+        data["defaultVersion"] = {
+          summary: mainlineRecord.description,
+          description: mainlineRecord.longDescription,
+          git: mainlineRecord.git,
+          exports: pkgExports
+        };
       } else {
         data["defaultVersion"] = _.last(data.versions);
       }
@@ -602,6 +608,16 @@ _.extend(PackageQuery.prototype, {
       data["dependencies"] = rewriteDependencies(localRecord.dependencies);
     }
 
+    var readmeInfo;
+    main.captureAndExit(
+      "=> Errors while reading local packages:",
+      "reading " + data["directory"],
+       function () {
+        readmeInfo = packageSource.processReadme();
+    });
+    if (readmeInfo) {
+      data["description"] = readmeInfo.excerpt;
+    }
     return data;
   },
   // Displays version information from this PackageQuery to the terminal in a
@@ -1060,7 +1076,6 @@ _.extend(ReleaseQuery.prototype, {
   // - packages: map of packages for this release version
   _displayVersion: function (data) {
     var self = this;
-    var data = self.data;
     Console.info("Release: " + data.track);
     Console.info("Version: " + data.version);
     Console.info(

tools/commands-packages.js

@@ -172,12 +172,74 @@ main.registerCommand({
 // publish a package
 ///////////////////////////////////////////////////////////////////////////////
 
+// Updates the metadata for a given package version. Prints user-friendly
+// messages if certain new values are invalid; calls to the packageClient to
+// perform the actual update.
+//
+// Takes in a packageSource and a connection to the package server. Returns 0 on
+// success and an exit code on failure.
+var updatePackageMetadata = function (packageSource, conn) {
+    var name = packageSource.name;
+    var version = packageSource.version;
+
+    // You can't change the metadata of a record that doesn't exist.
+    var existingRecord =
+          catalog.official.getVersion(name, version);
+    if (! existingRecord) {
+      Console.error(
+        "You can't call",  Console.command("`meteor publish --update`"),
+        "on version " + version + " of " + "package '" + name +
+          "' without publishing it first.");
+      return 1;
+    }
+
+    // Load in the user's documentation, and check that it isn't blank.
+    var readmeInfo;
+    main.captureAndExit(
+      "=> Errors while publishing:", "reading documentation",
+      function () {
+       readmeInfo = packageSource.processReadme();
+    });
+
+    // You are still not allowed to upload a blank README.md.
+    if (readmeInfo && readmeInfo.hash === files.blankHash) {
+      Console.error(
+        "Your documentation file is blank, so users may have trouble",
+        "figuring out how to use your package. Please fill it out, or",
+        "set 'documentation: null' in your Package.describe.");
+      return 1;
+    };
+
+    // Finally, call to the server.
+    main.captureAndExit(
+      "=> Errors while publishing:",
+      "updating package metadata",
+      function () {
+        packageClient.updatePackageMetadata({
+          packageSource: packageSource,
+          readmeInfo: readmeInfo,
+          connection: conn
+        });
+    });
+
+    Console.info(
+      "Success. You can take a look at the new metadata by running",
+      Console.command("'meteor show " + name + "@" + version + "'"),
+      "outside the current project directory.");
+
+    // Refresh, so that we actually learn about the thing we just published.
+    refreshOfficialCatalogOrDie();
+    return 0;
+}
+
+
 main.registerCommand({
   name: 'publish',
   minArgs: 0,
   maxArgs: 0,
   options: {
     create: { type: Boolean },
+    update: { type: Boolean },
     // This is similar to publish-for-arch, but uses the source code you have
     // locally (and other local packages you may have) instead of downloading
     // the source bundle. It does verify that the source is the same, though.
@@ -194,8 +256,22 @@ main.registerCommand({
 }, function (options) {
   if (options.create && options['existing-version']) {
     // Make up your mind!
-    Console.error("The --create and --existing-version options cannot " +
-                         "both be specified.");
+    Console.error(
+      "The --create and --existing-version options cannot",
+      "both be specified.");
+    return 1;
+  }
+
+  if (options.update && options.create) {
+    Console.error(
+      "The --create and --update options cannot both be specified.");
+    return 1;
+  }
+
+  if (options.update && options["existing-version"]) {
+    Console.error(
+      "The --update option implies that the version already exists.",
+      "You do not need to use the --existing-version flag with --update.");
     return 1;
   }
 
@@ -275,6 +351,13 @@ main.registerCommand({
     return 1;
   }
 
+  // If we just want to update the package metadata, then we have all we
+  // need. Don't bother building the package, just update the metadata and
+  // return the result.
+  if (options.update) {
+    return updatePackageMetadata(packageSource, conn);
+  }
+
   // Fail early if the package record exists, but we don't think that it does
   // and are passing in the --create flag!
   if (options.create) {

tools/files.js

@@ -307,6 +307,8 @@ files.fileHash = function (filename) {
   return fut.wait();
 };
 
+// This is the result of running fileHash on a blank file.
+files.blankHash = "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";
 
 // Returns a base64 SHA256 hash representing a tree on disk. It is not sensitive
 // to modtime, uid/gid, or any permissions bits other than the current-user-exec
@@ -1219,4 +1221,3 @@ files.pathwatcherWatch = function () {
   var pathwatcher = require('meteor-pathwatcher-tweaks');
   return pathwatcher.watch.apply(pathwatcher, args);
 };
-

tools/help.txt

@@ -599,25 +599,33 @@ Options:
 Publish a new version of a package to the package server.
 
 Usage: meteor publish [--create]
+       meteor publish --update
 
 Publishes a new version of a local package to the package server. Must be run
 from the directory containing the package. Reads the package.js file for version
 information, builds the package and sends both the package source and the built
 version of the package to the package server.
 
-This will only create one build of the package. If your package has multiple
-builds for different OS architectures, it will create a build for this machine's
-architecture. To publish a different build for the same version, run
-publish-for-arch.
+This will create at most one build of the package. If the package has an
+OS-dependent binary component, publishing will only register metadata about the
+package. To actually publish the package builds, use `meteor admin get-machine`
+and `meteor publish-for-arch`. Packages with no published builds cannot be added
+to applications.
 
-This will mark you as the only maintainer of the package. If you need to change
-maintainers and other metadata about this package & package version, take a look
-at the admin commands.
+This will mark you as the only maintainer of the package. You can use
+'meteor admin maintainers' to change package maintainers. For more information
+about admin commands, run 'meteor help admin'.
+
+Change the metadata for a given version of a package by running with the
+--update flag. That will set the git url, version summary, longform description
+and documentation in the database to their new values. You can use 'meteor show'
+to preview the results.
 
 Pass --create to create a new package.
 
 Options:
   --create   publish a new package
+  --update   changed metadata of a previously published version
 
 
 >>> publish-for-arch