3.0.0 pre-release (winstonjs#1342)

* [doc] CHANGELOG.md entry for 3.0.0 * [doc] Add ChrisAlderson to README.md * [doc] Make note of `finish` events vs callbacks and logged events. * [doc] Add more transport level options to the options documented as formats. * [doc refactor] Major overhaul / upgrade for Transport documentation. * [doc] Roadmap. * [doc dist] Remove refs to rc6 & release date. More keywords. Update maintainers.
Mizumaki · Jun 12, 2018 · 169c349 · 169c349
1 parent bf7451b
commit 169c349
Show file tree

Hide file tree

Showing 7 changed files with 630 additions and 536 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## v3.0.0 / 2018-06-12
+### GET IN THE CHOPPA EDITION
+
+- [#1332], (@DABH): logger.debug is sent to stderr (Fixed [#1024])
+- [#1328], (@ChrisAlderson): Logger level doesn't update transports level (Fixes [#1191]).
+- [#1356], (@indexzero) Move splat functionality into logform. (Fixes [#1298]).
+- [#1340], (@indexzero): Check log.length when evaluating "legacyness" of transports (Fixes [#1280]).
+- [#1346], (@indexzero): Implement `_final` from Node.js streams. (Related to winston-transport#24, Fixes [#1250]).
+- [#1347], (@indexzero): Wrap calls to `format.transform` with try / catch (Fixes [#1261]).
+- [#1357], (@indexzero): Remove paddings as we have no use for it in the current API.
+- [TODO]: REMAINS OPEN, NO PR (Fixes [#1289])
+- Documentation
+  - [#1301], (@westonpace) Cleaned up some of the documentation on `colorize`
+    to address concerns in [#1095].
+  - First pass at a heavy refactor of `docs/transports.md`.
+- Dependency management
+  - Regenerate `package-lock.json`.
+  - Upgrade to `logform@^1.9.0`.
+
 ## v3.0.0-rc6 / 2018-05-30
 ### T-MINUS 6-DAY TO WINSTON@3 EDITION
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,13 +1,13 @@
 # CONTRIBUTING
 
-TL;DR? The `winston` project is actively working towards getting `3.0.0` out of RC (currently `3.0.0-rc6`). 
+TL;DR? The `winston` project recently shipped `3.0.0` out of RC and is actively
+working towards the next feature release as it continues to triage issues. 
 
 - [Be kind & actively empathetic to one another](CODE_OF_CONDUCT.md)
 - [What makes up `winston@3.0.0`?](#what-makes-up-winston-3.0.0)
 - [What about `winston@2.x`?!](#what-about-winston-2.x)
 - [Could this be implemented as a format?](#could-this-be-implemented-as-a-format)
 - [Roadmap](#roadmap)
-  - [Version 3.0.0](#version-300)
   - [Version 3.1.0](#version-310)
 
 Looking for somewhere to help? Checkout the [Roadmap](#roadmap) & help triage open issues! Find an issue that looks like a duplicate? It probably is! Comment on it so we know it's maybe a duplicate 🙏.
@@ -46,12 +46,16 @@ const logger = createLogger({
 
 ## What about `winston@2.x`?!
 
-> _If you are opening an issue regarding the `2.x` release-line please know that 2.x work has ceased. The `winston` team will review PRs that fix issues, but as issues are opened we will close them._
+> _If you are opening an issue regarding the `2.x` release-line please know
+> that 2.x work has ceased. The `winston` team will review PRs that fix
+> issues, but as issues are opened we will close them._
 
 You will commonly see this closing `winston@2.x` issues:
 
 ```
-Development `winston@2.x` has ceased. Please consider upgrading to `winston@3.0.0-rc6`. If you feel strongly about this bug please open a PR against the `2.x` branch. Thank you for using `winston`!
+Development `winston@2.x` has ceased. Please consider upgrading to
+`winston@3.0.0`. If you feel strongly about this bug please open a PR against
+the `2.x` branch. Thank you for using `winston`!
 ```
 
 ## Could this be implemented as a format?
@@ -64,117 +68,53 @@ This can be accomplished with using [custom formats](https://github.com/winstonj
 
 # Roadmap
 
-Below is the list of items that make up the roadmap through `3.1.0`. We are actively triaging the open issues, so it is likely a few more critical path items will be added to this list before `3.0.0` gets out of RC.
+Below is the list of items that make up the roadmap through `3.3.0`. We are actively triaging the open issues, so it is likely a few more critical path items will be added to this list before the next release goes out.
 
-- [Version 3.0.0](#version-300)
 - [Version 3.1.0](#version-310)
+- [Version 3.2.0](#version-320)
+- [Version 3.3.0](#version-330)
 
 ## Legend
 
 - [ ] Unstarted work.
 - [x] Finished work.
 - [-] Partially finished or in-progress work. 
 
-## Version `3.0.0`
-
-### Show stoppers
-- [x] `silent` support.
-- [x] Finish `3.0.0` upgrade guide: https://github.com/winstonjs/winston/blob/master/UPGRADE-3.0.md
-- [ ] Triage all open issues since October 2017
+## Version `3.1.0`
 
 ### High priority issues (non-blocking)
-- [x] [#1144]: this is _the_ purpose of `winston`. If we cannot log at high-volume we cannot ship out of RC. There was [test coverage for this][stress-test] that should be failing, but isnt. _(Fixed by #1291)._
-- [ ] Error handling within formats [#1261]
-- [ ] Update `docs/transports.md`.
-
-### Core logging
-- [ ] Make `Logger.prototype.level` a setter to set level on transports.
-- [x] Remove `new winston.Logger` in favor of `winston.createLogger`.
-- [x] Finish implementation for `TransportStream` and `LegacyTransportStream`. 
-- [x] Move `TransportStream` and `LegacyTransportStream` into `winston-transport`.
-- [x] Move `winston/config.js` to `winston/config/index.js`
-- [x] **DEPRECATE** `winston.clone`
-- [x] Add convenience methods from `winston-transport`
+- [Browser support](https://github.com/winstonjs/winston/issues/287)
+  - [ ] Unit tests for `webpack` & `rollup` 
+- Benchmarking for `File` and `Stream` transports:
+   - [x] Benchmarking integration in `pino`.
+   - [ ] Upgrade `pino` to latest `winston`.
+   - See: https://github.com/winstonjs/logmark
+   - See also: https://github.com/pinojs/pino/pull/232
+- [ ] Move `logged` event into `winston-transport` to remove need for it in each individual Transport written _or remove the `logged` event entirely._
+
+### Increased code & scenario coverage
 - [-] Replace all `vows`-based tests.
-  - [x] `test/*-test.js`
-  - [-] `test/formats/*-test.js` 
   - [-] `test/transports/*-test.js` 
-- [x] Move `winston.config` into `triple-beam` around a base `Levels` class.
-  _(Fixed in `triple-beam@1.2.0`)_
-- [ ] Update to the latest `npm` levels (e.g. including `http`).
 - [ ] Code coverage tests above 80% for `winston` _(currently `~72%`)_.
-  - [x] Code coverage tests above 90% for `winston-transport`.
-  - [x] Code coverage tests above 90% for `logform`
   - [-] Core scenarios covered in `abstract-winston-transport`.
-  - [x] Code coverage tests above 60% for `winston-compat`.
-
-### Transports
-- [x] Implement `stream.Writable.writev` in `TransportStream`.
-- [x] Refactor all built-in transports to be TransportStream instances.
-  - [x] Console
-  - [x] File
-  - [x] Http
-  - [x] Steam
-- [ ] Move `logged` event into `winston-transport` to remove need for it in each individual Transport written.
-
-### Formats
-- [x] `winston.format.colorize()` format.
-- [x] `winston.format.prettyPrint()` format.
-- [x] `winston.format.uncolorize()` format.
-- [x] `winston.format.logstash()` format.
-- [x] `winston.format.cli()`
-- [x] String interpolation _(i.e. splat)_ via format
-- [x] Use of different formats across multiple Transports. e.g.:
-   - Colors on `Console`
-   - Not on `File`
-- [x] Mutable levels on `info` objects 
-   – Use `triple-beam` and `Symbol.for('level')`.
-   - Needed for `winston.formats.colorize()`. 
-- [x] Quieter finalized output using `Symbol.for('message')` 
-- [x] Filtering messages completely in a format.
-- [x] `winston.format.padLevels()` format.
-- [x] `humanReadableUnhandledException` should be the default
 
 ### Communications / Compatibility
-- [x] Add friendly(ish) deprecation notices for common changes.
-- [x] Create `winston-compat` to help with backwards compatibility for transport authors.  
-- [x] Update the `README.md` in `winston`.
-- [x] `README.md` for `winston-transport`.
 - [ ] `README.md` for `winston-compat`.
-- [x] `README.md` for `logform`.
-- [x] Migrate all `examples/*.js` to the new API.
+- [ ] All formats documented in `logform`.
+- [ ] All existing transports documented in `docs/transports.md`.
+
+## Version `3.2.0`
 
 ### Querying, Streaming, Uncaught Exceptions
-- [x] Uncaught Exceptions
-- [-] Querying
 - [-] Streaming
 
-### Other Miscellaneous API changes
-- [x] Move `LogStream` back to `Logger`.
-- [x] Add LogStream.prototype.configure from `winston@2.0.0`
-- [x] `winston.Container` instances no longer add any transports by default.
-- [x] Strip wrapping `(` `)` from all occurances of `new winston.transports.*)`
-
-### Benchmarking
-- [x] Benchmark against `winston@1.0.0` in `logmark`.
-- [x] Benchmark against `winston@2.0.0` in `logmark`.
-- [x] Benchmark JSON format against `bunyan` in `logmark`.
-- [x] Benchmark against `pino` in `logmark`.
-- [x] Submit PR for all `pino` benchmarks.
+### Communications / Compatibility
+- [ ] `winstonjs.org` documentation site.
 
-## Version `3.1.0`
+## Version `3.3.0`
 
-### High priority issues (non-blocking)
-- [Type definitions for TypeScript](https://github.com/winstonjs/winston/issues/1096)
-  - [x] Supporting libraries: `winston-transport`, `logform`
-  - [ ] `winston` itself 
-- [Browser support](https://github.com/winstonjs/winston/issues/287)
-  - [ ] Unit tests for `webpack` & `rollup` 
-- Benchmarking for `File` and `Stream` transports:
-   - [x] Benchmarking integration in `pino`.
-   - [ ] Upgrade `pino` to latest `winston`.
-   - See: https://github.com/winstonjs/logmark
-   - See also: https://github.com/pinojs/pino/pull/232
+### Querying, Streaming, Uncaught Exceptions
+- [-] Querying
 
 [winston-transport]: https://github.com/winstonjs/winston-transport
 [logform]: https://github.com/winstonjs/logform

diff --git a/README.md b/README.md
@@ -8,14 +8,7 @@ A logger for just about everything.
 
 [![Join the chat at https://gitter.im/winstonjs/winston](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/winstonjs/winston?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-## winston@3.0.0-rc6
-
-**We are pushing for a June 5th, 2018 release of `winston@3.0.0`**, currently
-`winston@3.0.0-rc6`.
-
-```
-npm i winston@next --save
-```
+## winston@3.0.0
 
 See the [Upgrade Guide](UPGRADE-3.0.md) for more information. Bug reports and
 PRs welcome!
@@ -99,8 +92,8 @@ logger to use throughout your application if you so choose.
 * [Querying Logs](#querying-logs)
 * [Further Reading](#further-reading)
   * [Using the default logger](#using-the-default-logger)
-  * [Events and Callbacks in `winston`](#events-and-callbacks-in-winston)
-  * [Working with multiple Loggers in winston](#working-with-multiple-loggers-in-winston)
+  * [Awaiting logs to be written in `winston`](#awaiting-logs-to-be-written-in-winston)
+  * [Working with multiple Loggers in `winston`](#working-with-multiple-loggers-in-winston)
 * [Installation](#installation)
 * [Run Tests](#run-tests)
 
@@ -118,7 +111,7 @@ const levels = {
   verbose: 3, 
   debug: 4, 
   silly: 5 
-}
+};
 ```
 
 ### Creating your own Logger
@@ -603,7 +596,7 @@ To colorize the standard logging level add
 winston.format.combine(
   winston.format.colorize(),
   winston.format.json()
-)
+);
 ```
 where `winston.format.json()` is whatever other formatter you want to use.  The `colorize` formatter must come before any formatters adding text you wish to color.
 
@@ -915,23 +908,25 @@ winston.configure({
 For more documentation about working with each individual transport supported
 by `winston` see the [`winston` Transports](docs/transports.md) document.
 
-### Events and Callbacks in `winston`
+### Awaiting logs to be written in `winston`
 
-Each instance of winston.Logger is also an instance of an [EventEmitter]. A
-`logged` event will be raised each time a transport successfully logs a
-message:
+Often it is useful to wait for your logs to be written before exiting the
+process. Each instance of `winston.Logger` is also a [Node.js stream]. A
+`finished` event will be raised when all logs have flushed to all transports
+after the stream has been ended.
 
 ``` js
 const transport = new winston.transports.Console();
 const logger = winston.createLogger({
   transports: [transport]
 });
 
-transport.on('logged', function (info) {
-  // `info` log message has now been logged
+transport.on('finished', function (info) {
+  // All `info` log messages has now been logged
 });
 
 logger.info('CHILL WINSTON!', { seriously: true });
+logger.end();
 ```
 
 It is also worth mentioning that the logger also emits an 'error' event which
@@ -1026,15 +1021,15 @@ yarn add winston
 
 ## Run Tests
 
-All of the winston tests are written with [`mocha`][mocha], [`nyc`][nyc], and [`assume`][assume].  They
-can be run with `npm`.
+All of the winston tests are written with [`mocha`][mocha], [`nyc`][nyc], and 
+[`assume`][assume].  They can be run with `npm`.
 
 ``` bash
 npm test
 ```
 
 #### Author: [Charlie Robbins]
-#### Contributors: [Jarrett Cruger], [David Hyde]
+#### Contributors: [Jarrett Cruger], [David Hyde], [Chris Alderson]
 
 [Transports]: #transports
 [Logging levels]: #logging-levels
@@ -1045,7 +1040,6 @@ npm test
 [additional transports]: docs/transports.md#additional-transports
 
 [RFC5424]: https://tools.ietf.org/html/rfc5424
-[EventEmitter]: https://nodejs.org/dist/latest/docs/api/events.html#events_class_eventemitter
 [util.format]: https://nodejs.org/dist/latest/docs/api/util.html#util_util_format_format_args
 [mocha]: https://mochajs.org
 [nyc]: https://github.com/istanbuljs/nyc
@@ -1056,3 +1050,4 @@ npm test
 [Charlie Robbins]: http://github.com/indexzero
 [Jarrett Cruger]: https://github.com/jcrugzz
 [David Hyde]: https://github.com/dabh
+[Chris Alderson]: https://github.com/chrisalderson