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: https://github.com/meteor/meteor/pull/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: https://github.com/meteor/meteor/pull/3375
The ‘show’ command has been completely rewritten. It has different output
and now does the following:
- Interacts with local package versions. Checks in the local package catalog, and
returns the local versions along with the server versions. When ‘meteor show’ is
run with a specific version request (‘meteor show foo@<version>’), default to
showing the local package version (but show a message that a server version is
available). Running ‘meteor show foo@local’ will always show the local version
(useful for version-less local packages).
- Simplify the interface. Instead of various ‘show-*’ flags, we only have one: show-all.
By default, we only show the top 5 official (non-prerelease) unmigrated versions of a
package (+ local version, if applicable). This can be overridden with ‘show-all’, and we
let the user know that more versions are available. For releases, ‘show-all’ will show
non-recommended releases.
- Display publication time for non-local package versions. This makes it easier to run
‘meteor show <name>’ and see if <name> is actively maintained. For local packages,
we display the root directory (useful for large apps or running with the
LOCAL_PACKAGE_DIRS variable, for example).
- For non-local package versions, show if the version is ‘installed’ (downloaded into the
warehouse). This involved minor changes to tropohouse.js. The idea is that this should
give a pretty good clue whether the version can be added offline.
- Show version dependencies. This should help the user understand, track down and
debug constraint solver failures.
- Do not show version architectures except in —ejson mode.
- Allow an ‘—ejson’ flag to get the output in EJSON format. That should make scripting
easier. (As a bonus, for release versions, the EJSON output acts as a nice template
for the release configuration file.)
The search command now does the following:
- Interacts with local package versions. Specifically, local versions override equivalent
server versions. Also, ‘search’ works on local packages (so, for example,
‘meteor search troposphere’ inside the package server app will give you the troposphere
package).
- Allows an ‘—ejson’ flag to get the outout in EJSON format.
Minor changes to some minor testing infrastructure:
- A new skeleton package, package-for-show. Its versions contain different
values for various metadata, so we can test that metadata comes from
the right version.
- In several places, replace the pattern of copying around
package.js files with using the replace function on a placeholder
string. (Mostly, as applied to package versions).
This is based on these hackpads: https://mdg.hackpad.com/Showing-Package-Metadata-HdGo3Lzx3hR
and https://mdg.hackpad.com/Meteor-Search-Output-1xxEzrAK9YU.
This is a breaking change to package-version-parser.
A PackageConstraint used to look like this:
```
{ name: String,
constraintString: String,
constraints: [{version: String|null,
type: String}]}
```
Now it looks like this:
```
{ name: String,
constraintString: String,
vConstraint: {
raw: String,
alternatives: [{versionString: String|null,
type: String}]}}
```
Where (vConstraint instanceof VersionConstraint) and
(vConstraint.raw === constraintString).
This achieves several desirable changes at once.
* `constraint.constraints` for the disjuncts in “1.0.0||2.0.0”
was confusing. `alternatives` is better.
* Having a class for VersionConstraint will come in handy because
we can add methods to it, and we can use it in the constraint
solver to represent the problem statement.
* The names “vConstraint” and “versionString” are a little verbose,
but there really shouldn’t be a lot of code that dives into this
structure, and I really wanted to avoid anyone ever writing:
`constraint.constraint.alternatives[0].version`, and then wondering
what sort of object that was (not a parsed PackageVersion! we could
parse eagerly but that might be slow).
At least, not directly. When the tool wants to parse a string of the
form “package@version,” it now uses utils.parsePackageAtVersion.
This way, if I make a breaking change to PV.parseConstraint, I only have
to change a few call sites.
It was already set for most common commands, and was unnecessarily not
set for others.
The following commands are remaining "pretty: false":
- Commands that just print machine-parseable text: --version, --arch,
admin members (without --add or --remove), mongo --url,
authorized (without --add or --remove), whoami, list-organizations, list-sites
- Commands that just switch over to another codebase's interactive
command: mongo without --url, admin get-machine, shell
The following commands used to be implicitly "pretty: false" and now
will be pretty:
- A bunch of troposphere admin commands: set-banners, recommend-release,
change-homepage, set-unmigrated, set-latest-readme
- A few accounts/deploy related commands: logs, claim, login, logout
- remove-platform, reset, self-test
- admin maintainers (which unlike admin members and authorized prints an
English header before the user list; maybe this is a mistake)
It might make sense in the future to further separate "pretty means can
show progress bars if the output is a TTY" from "pretty means can use
chalk styling and unicode bullets".
Fixes#3162.
This will be useful when we want to be smart with windows file paths later
Also, all of the file calls are asynchronous with fibers now, which comes with
many benefits.
This is a combination of 23 commits. Original messages:
Wrap a large number of fs calls inside files.*
Convert a few more fs calls to files.*
More moving fs.* to files
Implement read/write streams and open/read/close
Get rid of fs from auth.js
Remove fs and unused imports from catalog-local and catalog-remote
Remove unused imports from catalog.js
Replace a whole lot of fs calls
Fix error
Migrate a lot more fs. calls to files.
Add a temporary symlink method
Convert old test to files.*
Use files.pathX instead of path.x everywhere
Replace path.x to files.pathX in tests
Small fixes to files.js and one rename
Make cleanup run in a fiber
Make wrapping functions take function name in case we need it
Add some timeouts and stuff to HCP tests
wrapFsFunc also makes a sync version of the function
Sometimes you just don't want to yield!
Make sure JsImage readFromDisk doesn't yield
Remove unused imports from npm test
Change order of test now that some things don't yield
Fix missing files import, and add a debug error printout
Typically, there is a delta due to adding the test slice of the
published package, but there's no reason to tell the user about this or
save it in .meteor/versions.
Specifically, we only compile them if there's a cordova platform in the
current project, or if we are publishing the package.
(Ideally, we wouldn't require every published package to have
web.browser and web.cordova unibuilds --- we'd just publish a 'web'
unibuild unless there's actually a difference between the two. But we
are not there yet.)
This adds an extra flag to isopack-buildinfo.json, so that we know to
rebuild all the isopacks when we add the first cordova platform (or
remove the last cordova platform).
The implementation around publish is a little clunky; if you're in a
non-Cordova app and run meteor publish, it will rebuild all the packages
with web.cordova, and the next time you prepare the app it will rebuild
them again without it. It does work though.
Fixes#3274.
Fixes#2846. Fixes#2847. Fixes#2979.
Errors in the build process that could be fixed by refreshing the
catalog now cause the catalog to refresh, assuming we have not already
refreshed it recently and that we are not offline.
These commands now don't need to refresh at startup: remove, run, debug,
create, build, bundle, deploy, test-packages, rebuild, and self-test
It should be OK for create to throw SpringboardToLatestRelease even
without refreshing, since release.latestKnown is still something we know
about.
I think that this makes the API too complicated, but we might want to treat
directories the same way that we do commands (use some chalk when needed,
do not wrap, etc). This introduces the Console.directory function.
Of course, it is not really clear to me what happens if a directory is inside a command.
(ex: 'cd <directory>'). Right now, there is no difference. It makes sense to me that
we might want to keep the entire command the same style, so I am not wrapping those
in additional Console.directory units for now.
- Wrapping URLs in Console.url. Making Console.url not word-wrap URLs,
on the off-chance that a URL could be wrapped.
- Creating a doNotWrap function on the Console. Call this on things that
are not commands or URLs, but still should not be wrapped.
- fixing minor mistypes, removing a comment about the dev bundle on the
Windows branch.
Includes the following changes to Console.js:
- Console.info, Console.warn, Console.debug and Console.error now automatically
line-wrap the output to 80 characters, or the width of the terminal screen (if
known). This is in line with our current style guide on how things should be wrapped!
- Sometimes, there are parts of text that we don't want to line-wrap. For example, if we are
telling the user to run 'meteor long-command --with --options' we don't want to
have a newline in the middle of that! Wrap those commands in Console.command, like
this:
Console.info("something and then run", Console.command(command), "and then");
This also makes them bold if chalk is on, as a nice bonus. So, if we ever turn
chalk back on, the bolding of commands will be more consistent.
- Sometimes, there is bulkier output that we don't want to format at all, including
line-wrapping: log snippets, stack traces, JSON output, etc. In that case, we can use
Console.rawInfo, Console.rawError, Console.rawWarn and Console.rawDebug. Don't use
Console.command inside the raw* functions! It won't be processed (at all).
- There are fancier things that we can do, other than just simply wrapping things.
We can indent:
" Start here and then when wrapping
continue over here".
We frequently do this for commands, for example. In the past, we did this manually --
but we can't do this for long messages that might get wrapped, and anyway, it is
good to codify this instead of counting spaces. Allows us to be better about consistency,
for example.
- We can also add a bulletPoint, which is a small notice in the beginning that looks like
this:
" => Start here and then when wrapping
continue below the bulletPoint".
Since it is a elss intuitive option, I have wrapped most of the time that we use a
bulletPoint into helper functions on the Console.js.
- Some common bulletpoints that we use are:
ASCII Checkboxes (Console.success)
ASCII X-s (Console.failWarn and Console.failInfo)
=> (Console.arrowError, Console.arrowWarn, Console.arrowInfo)
WARNING (Console.labelWarn)
The => are sometimes indented, so they take an optional indent argument, showing how
many spaces to indent by.
The wrapper interface would be less complicated, if there was a more unified conceit behind our
terminal messages. If there is one, it is not documented. My hope is that, in many cases,
moving these to Console will make it easier for someone with great product sense to
clean up our terminal messages. It will also make it easier to write such messages, since
it will be easier to follow an accepted standard.
In the codebase outside of Console:
- Went through and looked at our use of Console.error/info/etc, replacing with rawError/etc
whenever approporiate.
- Went through and modified most of 'stdout' and 'stderr' calls to use the new functions.
I made an exception for stuff that doesn't want a new line at the end, or otherwise does
weird things (ex: print user logs directly), on the basis that, at this juncture, it is
better to be safe than to be sorry.
- Long messages no longer need to break the code style guide by ignoring indentation rules.
Fixed that where approporiate.
- Fixed the tests! A number of our stock messages are actually longer than 80 chars.
- Personal favourite: The Android license agreement is now line wrapped! Much better experience.
- There is some more work to do on:
- longform help (currently comes with built-in linebreaks, would have to change the entire
mechanism for how that works)
- Buildmessage sometimes has headers that start with =>, but they are short. I didn't want to
pass wrapper options all the way to main.captureOrExit before merging the rest of this and
making sure that we like it. Since these messages are fairly short, I don't think that's
likely to be a serious problem.
I hope that this makes life easier for us in the future! No more counting chars, no more breaking
the style guide. Better experience for users with wider terminals (or even shorter terminals!).
Let's give this a try.
This means that the first command won't need to do a big build (and
print lots of package changed notifications). Similar to what 'meteor
create' does.
Also add --prepare-app command.
This command was changed in 0.9.0 to do something of questionable use,
and was temporarily unimplemented as part of work on #3006. It now does
something relatively simple to describe: It prepares your current app
for build, and in addition, it downloads EVERY package in your current
release and builds EVERY available local package (including those which
you are not using in your app).
This reimplements functionality that had been removed as part of the
`isopack-cache` branch refactoring.
Information about package changes is encapsulated inside a
PackageMapDelta object on the ProjectContext. It is the responsibility
of the command that prepares the ProjectContext to choose to call
projectContext.packageMapDelta.displayOnConsole at the appropriate time
if it wishes to display changes.
Part of #3006.
- don't crash when listing upgraders (2 bugs, introduced on this branch)
- successfully write banners-shown file so that we sometimes print
shorter banners (introduced with sqlite)
- in self-test tropohouse, keep the sadly necessary symlinks
autoupdate test file now passes!
