THIS NEWS FEED IS NO LONGER ACTIVE. It will eventually be moved to the Rush Stack site.
>> For news about Rush, please see https://rushjs.io/pages/news/
>> For news about API Extractor, please see https://api-extractor.com/pages/news/
June 29, 2018 - Rush 5 released
After a couple months of internal builds (using the "dev" disttag), today we finally published the official release of Rush 5. Unlike previous releases which were generally backwards compatible, Rush 5 has a number of breaking changes. That's why we let it bake so long before releasing.
NOTE: These "breaking changes" should NOT affect you until you update your rush.json file to specify "rushVersion": "5.0.0". Otherwise, Rush's "version selector" feature ensures that you will continue to get the Rush 4 behavior inside your repo folder, even when your globally installed "rush" command is version 5.
Early next week we'll post some detailed docs and Rush 4->5 migration instructions. But here's a quick summary of the main changes:
rush generateis replaced by a simplified commandrush update(can also be used instead ofrush install, except for CI jobs)- Some command-line options and config file formats have changed, although the old->new mapping is pretty straightforward
- There’s a new
rushxexecutable that works likenpm run(but with command-line help and eventually options validation) - You can now define global custom commands, that run once for the entire repo
- We’ve formalized how a CI job installs Rush and other tools, via the new common/scripts/install-run.js and install-run-rush.js scripts (which are populated by Rush)
- The .npmrc file now supports custom environment variables for auth tokens
- People can use the RUSH_PREVIEW_VERSION environment variable to privately preview new releases of Rush
- A bunch of bug fixes
See the CHANGELOG.md file for a full list of changes in this release.
March 26, 2018 - API Extractor now supports *.d.ts rollups
As of version 5.6.0, API Extractor can now generate rollups for your *.d.ts files, similar to how Webpack generates rollups for your *.js files. It can also trim definitions according to their release tags: For example, if a member is marked as @internal, it no longer show up in the VS Code IntelliSense for developers targeting a production release. Check out the Feature walkthrough page for an example usage scenario. The Creating .d.ts rollups page explains how to configure it. The *.d.ts rollup feature was several months in development, and involved a significant overhaul of the semantic analyzer that in the future will allow API Extractor to support a much broader range of TypeScript constructs (which has been a frequent user request).
March 5, 2018 - TSDoc project is live
We've launched a new GitHub project Microsoft/TSDoc which aims to standardize the JSDoc-style tags used for TypeScript doc comments. Eventually API Extractor's AEDoc tags will integrated with the TSDoc standard, to improve interoperability with other documentation tools.
January 8, 2018 - Rush now has preliminary support for PNPM
We have added support in Rush for the PNPM package manager. PNPM has several advantages over NPM, including performance, disk efficiency, rigor and simplicity. The primary idea behind PNPM is to install packages a single time, and construct your node_modules folder using only symlinks. By comparison, NPM imposes a tree of physical folders that often requires excessive duplication of the exact same contents.
We just enabled PNPM for use by people who work in the web-build-tools repository!
Testing locally, in web-build-tools, PNPM appears to greatly improve rush generate speeds!
| PNPM | NPM | |
|---|---|---|
| install (clean) performance | 231 s | 304 s |
| install (clean) disk usage | 175 mb | 200 mb |
| rush link (clean) | <1 s | 60 s |
| generate (not clean) | 48 s | 271 s |
Benefits
- PNPM eliminates the annoying race condition issue in NPM!
- Disk efficiency - unlike NPM, PNPM will install a specific version of a package only once on disk, saving many gigabytes (reducing node_modules folder size from 10-30%).
- Performance – since PNPM only install packages a single time, then constructs the dependency graph using much cheaper symlinks, it is also much faster than PNPM. This in turn makes rush install much faster.
- With PNPM, “rush generate” is much faster because we no longer have to delete the node_modules folder and do a full re-install.
- Rigor – PNPM creates links in the node_modules folder only for direct dependencies. This means you can’t accidentally
require()things that aren’t in your package.json, which can lead to strange errors for consumers of your library. - Simpler structure – this will enable to more easily implement Rush feature requests such as repo-to-repo linking.
How to use PNPM
Simply change the npmVersion field in your package.json to pnpmVersion, as documented in the "How to tell Rush which package manager to use" section of this page.
November 3, 2017 - Rush 4 released!
We’re excited to announce Rush version 4! First things first...
What repo maintainers need to do:
- To upgrade, repo maintainers should delete
rushMinimumVersionfrom rush.json, and replace it with"rushVersion": "4.0.0" - Or, if you’re not ready to migrate yet, make sure your
rushMinimumVersionspecifies the version you want developers using, because Rush 4’s version selector will install that for them - If you rely on Rush command-line options that are being removed (
--vso,--npm,--ship,--minimal,--production,--colors), you’ll need to update your build scripts - If you rely on Rush invoking the
testandcleanscripts in your package.json, you’ll need to update your build scripts
Regular developers don’t need to do anything. These changes should be transparent to the everyday developer experience. And here's what's new under the hood...
Simplified build model
Prior to Rush 4, when you ran "rush rebuild", it would do the following for each project:
Old Rush 3 Behavior
-
Execute the
"clean"script from package.json -
Execute the
"test"script from package.json (or if"test"is not found, use the"build"script instead); the--coloroption was always appended to the scriptIf the Rush command line included the options
--vso,--npm,--ship, or--minimal, they were also appended to the"test"(or"build") script.
New Rush 4 Behavior
-
Execute the “build” script from package.json. By default NO options are appended.
The options
--vso,--npm,--ship, and--minimalare no longer built-in to Rush. However, we have a new feature that allows repo maintainers to define their own options. This is much more flexible! (See here for detailed documentation.)
To minimize the migration pain, we’ve provided a legacy-command-line.json sample that shows how to restore these options. However, if you had "clean" or "test" scripts in your package.json files, you will still need to merge their implementation into your "build" script (e.g. by defining a --no-clean or --no-test option).
Note that the --color option is no longer appended. This was a workaround for a problem where the colors and chalk libraries don't show colors when Rush executes your scripts in parallel and collates their output. With Rush 4, we recommend for your build scripts to show colors by default, and then use a --no-color option for cases such as Travis logs. Since colors and chalk look at the argv variable, you can just add something like this to the top of your Gulpfile:
if (process.argv.indexOf('--no-color') === -1) {
process.argv.push('--color');
}
For a complete migration example, here’s the PR we used for upgrading web-build-tools to Rush 4.
Improvements for “rush change”
Rush 4 includes some improvements to make change tracking more pleasant:
- In the past, if you committed more fixes to your branch after running
rush change, you couldn’t run it again without first deleting the JSON files it created. That has been fixed! rush changenow allows you to enter multiple changes for the same project (e.g. for a PR that fixed several bugs)- We also fixed a usability issue where
rush changewould prompt for irrelevant release types (e.g. “major” when the major is supposed to be locked) - In the change logs, the message “Changes not tracked” now says “Version update only” to clarify that changes are being tracked
The Rush version selector
In the past, developers could install any version of Rush that satisfies the rushMinimumVersion field. This led to several problems:
- When a bug or compatibility issue occurred, people would have trouble reproducing it
- If the latest Rush release contained a bug, there was no easy way to downgrade everyone while waiting for a fix
- A certain class of bugs (e.g. shrinkwrap file format changes) arise only when your Rush version is different from the person who ran
rush generate
Rush 4 solves all these problems by replacing rushMinimumVersion with an explicit rushVersion. When you invoke Rush 4 from the command line, the “version selector” feature will examine this setting and automatically install that version of the engine (i.e. rush-lib package). Regardless of which version of Rush a developer installed globally, inside a given repo the Rush tool will behave like the release specified in rush.json. Even the rush –h command line help will be from this version. (It even works for previous Rush versions -- Rush 4 will simply install the rushMinimumVersion.)
The version selector helps repo maintainers by ensuring deterministic build behavior for all users. It helps developers by allowing them to work in different repos without worrying about which version of Rush they have installed. (Unless the selector itself has a bug, you may never need to upgrade Rush again!) Lastly, it helps the people who work on Rush by making regressions easier to diagnose and avoiding a fire drill when an issue is found.
NOTE: Don’t forget to edit rush.json periodically to upgrade your
rushVersion. Otherwise, you’ll be stuck on the old version indefinitely. :-)
API cleanup for rush-lib
Moving all the Rush code into rush-lib enabled us to remove a bunch of internal utilities that were cluttering up the API. The leaner, meaner rush-lib package is now documented in our API reference.
NPM 5 workaround
So far NPM 5 has been a... rather rough ride. As of version 5.5.1 it still has regressions that are causing trouble for people. Rush 4 includes some workarounds that should eliminate the recent issue that was blocking people from using NPM 5. (Our long term strategy is still to move to PNPM, which should be available soon as an “opt-in” feature. The PR is here.)
September 5, 2017 - Changes requiring action in Rush 3.0.15
Rush 3.0.15 changes some behavior in the temp modules folder to be compatible with NPM 5 and PNPM. You will likely see the following error during installation:
ERROR: Failed to parse package.json for : Invalid version: "file:projects/.tgz"
This is due to your shrinkwrap file needing a small update for Rush 3.0.15. To fix the issue, run rush generate and checkin the changes to the shrinkwrap file. (Alternately, you could change all the "file:projects/{PROJECT_NAME}" references in the shrinkwrap to "file:/{PROJECT_NAME}.tgz".)
July 25, 2017 - You can now use TypeScript 2.4!
Hurray, @microsoft/gulp-core-build-typescript version 3.3.0 finally upgraded our compiler to TypeScript 2.4.2! Big thanks to @iclanton for getting this implemented and migrating everything!
We were stuck on 2.2.2 for quite awhile, and many people asked about this. We tend to procrastinate compiler migrations internally because our repo is pretty big. (It always takes about a week of work to get our projects upgraded.) We recognize that people with smaller code bases like to use the latest compiler. We're working on a gulp-core-build backlog item that will make it easier to switch between supported compiler versions. This will allow migrations to happen piecemeal, and allow early adopters to stay more current.
(BTW it is already technically possible to swap out the compiler using TypeScriptConfiguration.setTypescriptCompiler() in your Gulpfile. However, we cannot provide support for people who do that. There's too much potential for migration noise, buggy releases, and compiler API incompatibilities for the tslint and API Extractor tasks.)
The official TypeScript release notes are here:
Here's a summary of the main issues that we encountered while migrating our own projects this time:
Compiler changes:
- The
Mapconstructor from @types/es6-collections no longer works with literals. For example,new Map([['a', 1], ['b', 2]]);requires a clunky typecast. We're going to solve this by migrating to the compiler's lib.es2015.collection.d.ts for our collection typings. - The compiler is much more paranoid about "weak types", i.e. interfaces whose properties are all optional, and therefore compatible with anything. We hit this in a number of places.
- Overall the compiler is much more accurate at comparing types, which found some real bugs in our code.
- We saw at least one race condition behave differently due to the new compiler output.
TSLint changes:
- The no-use-before-declare rule is now more accurate, so you may need to rearrange some members, types, classes, and enums. For certain cyclic references, a TSLint exception is required.
- The no-unused-expression rule is more thorough, which causes warnings for unit tests that use the cute syntax like "
expect(a[0], a[1]).to.be.equal('Title');". Don't do that; useassert()instead. - The member-ordering rule is now more strict.
- The no-shadowed-variable rule now catches a bunch of stuff that it missed before. In particular, lots of local variables now conflict with imported package names, and need to be renamed to something different.
Some additional issues when upgrading @types/react from 0.14.46 to 15.0.38:
voidis no longer allowed in component props or state types. That had to change in many places.- office-ui-fabric-react has not yet been upgraded to TS 2.4, so it also hasn't gotten the new React typings. This means that there are some props inheritance issues that required typecasts
Overall TypeScript 2.4 is a pretty nice improvement that brings a lot of interesting new features. Have fun!
June 20, 2017 - API Extractor now detects some common mistakes
The 2.2.0 release of API Extractor introduces some new warnings that may require some minor migration work when you upgrade. In the past certain conventions were documented but easy to overlook in a review. With this update, the tool catches some important mistakes and reports them as warnings.
You will now see a warning:
- If you forget to add a release tag for a package export
- If a definition is marked as
@internalbut is missing the underscore prefix - If a definition was NOT marked as
@internalbut DOES have an underscore prefix - If you use the
@summarytag, which is not necessary for AEDoc
Lastly, constructors no longer require documentation. Instead of flagging them as (undocumented), a generic summary will be generated: "Creates a new instance of the ____ class"
May 15, 2017 - Rush 3 released!
This is a breaking change. In order to upgrade, you must migrate your repo. In the past, Rush upgrades have always been backwards compatible, but this time we made some structural changes that would be expensive to support. (We're planning a future feature that will allow Rush to emulate old versions of itself, but it's not ready yet.)
NOTE: If your repo hasn't been upgraded yet, you can use npm install -g @microsoft/rush@2.5.0 to install the old version.
What's new in Rush 3
-
Streamlined workflow: Hurray! You no longer need to run
rush generateevery time you modify a package.json file. Just run a simplerush install, and in most cases Rush will find what it needs in your existing shrinkwrap file. You can even add new projects. Under this new model, you never need to runrush generateunlessrush installexplicitly tells you to. This is a big change that eliminates a lot of hassle from your everyday Rush experience. -
Simplified .gitignore: When setting a new repo, you no longer need to guess about which files to commit. Every temporary file for Rush has been moved under ./common/temp, so now a single .gitignore rule is all you need.
-
Simplified configuration: We eliminated some obscure and deprecated settings, and consolidated Rush's config files in a single folder ./common/config/rush. (rush.json still goes at your repo root.)
-
Improved package approval: The old "packageReviewFile" setting has been replace by two separate config files browser-approved-packages.json and nonbrowser-approved-packages.json. (When the list was combined in a single file, people didn't realize there were two sections, so this solves that problem.)
-
Shorter command line: We renamed some Rush command-line verbs:
rush checkis nowrush scan, andrush check-versionsis now justrush check. -
Infrastructure improvements: The
rush linkcommand now skips if nothing has changed. The change log data files were redesigned to support subset publishing (coming soon!). More operations use the AsyncRecycleBin optimization. Better unit test coverage.
Migration checklist
When upgrading a repo to use Rush 3:
- Delete "common/package.json" and "common/temp_modules/..." and remove them from Git
- Move your "npm-shrinkwrap.json" and (if needed) ".npmrc" files into the "common/config/rush" folder.
- If you have a "pinnedVersions.json" file, rename it to "pinned-versions.json" and move under "common/config/rush" as well.
- Delete the "commonFolder" and "useLocalNpmCache" settings from your rush.json file.
- If you use the "packageReviewFile" feature: Split the review file into "browser-approved-packages.json" and "nonbrowser-approved-packages.json" files, and move them to "common/config/rush". In rush.json, delete the "packageReviewFile" setting, and move your "reviewCategories" into an "approvedPackagesPolicy" block like this:
"approvedPackagesPolicy": {
"reviewCategories": [ "first-party", "third-party", "prototype" ],
"ignoredNpmScopes": [ "@types" ]
},
- Delete extraneous .gitignore rules from the old Rush; see Setting up your repo for a .gitignore example.
- Rush "rush generate" again
- If you have any tools that use @microsoft/rush-lib, you may need to update their code.
May 1, 2017 - API Extractor now supports tables of constants
If you have a bunch of static functions, API Extractor generally recommends to put them inside a class object like this:
/**
* Some utilities for working with text strings.
* @public
*/
export class Text {
private constructor() { }
/** Format a text string. */
public static format(text: string, ...values: any[]): string;
/** If the string is longer than maxLength, truncate it and add "..." at the end. */
public static shortenWithElipsis(text: string, maxLength: number): string;
/** The three dots ("..."). */
public static ELIPSIS: string = '...';
}
Although TypeScript supports a namespace keyword, we currently recommend classes because they have several advantages:
- Ability to define properties with getters/setters
- Members are marked as const, whereas
export functionis a function pointer.
However, for a table of string constants, this can be inefficient because webpack's optimizer always bundles all the class members, even if most of them are unused. To support this scenario, API Extractor now recognizes this syntax for simple tables of constants:
/**
* Constants for working with file paths.
* @public
*/
export namespace PathConstants {
/** The NPM package folder name. */
export const nodeModulesFolder: string = 'node_modules';
/** The NPM package configuration file name. */
export const packageJsonFilename: string = 'package.json';
/** The maximum folder depth supported by the tool. */
export const MAXIMUM_FOLDER_DEPTH: number = 10;
}
The generated API documentation will include the values of the constants. Pretty handy!