Skip to content

Latest commit

 

History

History
184 lines (149 loc) · 7.67 KB

CONTRIBUTING.md

File metadata and controls

184 lines (149 loc) · 7.67 KB
Raw

CONTRIBUTING

TL;DR? The winston project is actively working towards getting 3.0.0 out of RC (currently 3.0.0-rc5).

Looking for somewhere to help? Checkout the 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 🙏.

What makes up [email protected]?

As of [email protected] the project has been broken out into a few modules:

Let's dig in deeper. The example below has been annotated to demonstrate the different packages that compose the example itself:

const { createLogger, transports, format } = require('winston');
const Transport = require('winston-transport');
const logform = require('logform');
const { combine, timestamp, label, printf } = logform.format;

// winston.format is require('logform')
console.log(logform.format === format) // true

const logger = createLogger({
  format: combine(
    label({ label: 'right meow!' }),
    timestamp(),
    printf(nfo => {
      return `${nfo.timestamp} [${nfo.label}] ${nfo.level}: ${nfo.message}`;
    })
  ),
  transports: [new transports.Console()]
});

What about [email protected]?!

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 [email protected] issues:

Development `[email protected]` has ceased. Please consider upgrading to `[email protected]`. 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?

Before opening issues for new features consider if this feature could be implemented as a custom format. If it is, you will see your issue closed with this message:

This can be accomplished with using [custom formats](https://github.com/winstonjs/winston#creating-custom-formats) in `[email protected]`. Please consider upgrading.

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.

Legend

  • Unstarted work.
  • Finished work.
  • [-] Partially finished or in-progress work.

Version 3.0.0

Show stoppers

High priority issues (non-blocking)

  • [#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 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.
  • Remove new winston.Logger in favor of winston.createLogger.
  • Finish implementation for TransportStream and LegacyTransportStream.
  • Move TransportStream and LegacyTransportStream into winston-transport.
  • Move winston/config.js to winston/config/index.js
  • DEPRECATE winston.clone
  • Add convenience methods from winston-transport
  • [-] Replace all vows-based tests.
    • test/*-test.js
    • [-] test/formats/*-test.js
    • [-] test/transports/*-test.js
  • Move winston.config into triple-beam around a base Levels class. (Fixed in [email protected])
  • Update to the latest npm levels (e.g. including http).
  • Code coverage tests above 80% for winston (currently ~72%).
    • Code coverage tests above 90% for winston-transport.
    • Code coverage tests above 90% for logform
    • [-] Core scenarios covered in abstract-winston-transport.
    • Code coverage tests above 60% for winston-compat.

Transports

  • Implement stream.Writable.writev in TransportStream.
  • Refactor all built-in transports to be TransportStream instances.
    • Console
    • File
    • Http
    • Steam
  • Move logged event into winston-transport to remove need for it in each individual Transport written.

Formats

  • winston.format.colorize() format.
  • winston.format.prettyPrint() format.
  • winston.format.uncolorize() format.
  • winston.format.logstash() format.
  • winston.format.cli()
  • String interpolation (i.e. splat) via format
  • Use of different formats across multiple Transports. e.g.:
    • Colors on Console
    • Not on File
  • Mutable levels on info objects – Use triple-beam and Symbol.for('level').
    • Needed for winston.formats.colorize().
  • Quieter finalized output using Symbol.for('message')
  • Filtering messages completely in a format.
  • winston.format.padLevels() format.
  • humanReadableUnhandledException should be the default

Communications / Compatibility

  • Add friendly(ish) deprecation notices for common changes.
  • Create winston-compat to help with backwards compatibility for transport authors.
  • Update the README.md in winston.
  • README.md for winston-transport.
  • README.md for winston-compat.
  • README.md for logform.
  • Migrate all examples/*.js to the new API.

Querying, Streaming, Uncaught Exceptions

  • Uncaught Exceptions
  • [-] Querying
  • [-] Streaming

Other Miscellaneous API changes

  • Move LogStream back to Logger.
  • Add LogStream.prototype.configure from [email protected]
  • winston.Container instances no longer add any transports by default.
  • Strip wrapping ( ) from all occurances of new winston.transports.*)

Benchmarking

  • Benchmark against [email protected] in logmark.
  • Benchmark against [email protected] in logmark.
  • Benchmark JSON format against bunyan in logmark.
  • Benchmark against pino in logmark.
  • Submit PR for all pino benchmarks.

Version 3.1.0

High priority issues (non-blocking)