From d720b4fe4ad800b726da6b0f43c8454c4310fe8d Mon Sep 17 00:00:00 2001 From: Aseem Kishore Date: Sat, 1 Oct 2022 09:43:31 -0700 Subject: [PATCH] Improve readme (e.g. explain JSON5 better!) (#291) * Explain JSON5 better. Proactively emphasize that this is for config file type use cases, not machine-to-machine communication (the #1 misunderstanding or objection to JSON5). * Market/sell it better. The stats and company/project names are exciting! =) * Link to blog post. This doesn't need to be front-and-center though; just added it to my name in the credits. * Emphasize ES5 compatibility. Just put a stake in the ground here and preempt feature requests we'll never accept. --- README.md | 48 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c23663d8..ebd0d42f 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,33 @@ Status] [![Coverage Status](https://coveralls.io/repos/github/json5/json5/badge.svg)][Coverage Status] -The JSON5 Data Interchange Format (JSON5) is a superset of [JSON] that aims to -alleviate some of the limitations of JSON by expanding its syntax to include -some productions from [ECMAScript 5.1]. - -This JavaScript library is the official reference implementation for JSON5 -parsing and serialization libraries. +JSON5 is an extension to the popular [JSON] file format that aims to be +easier to **write and maintain _by hand_ (e.g. for config files)**. +It is _not intended_ to be used for machine-to-machine communication. +(Keep using JSON or other file formats for that. 🙂) + +JSON5 was started in 2012, and as of 2022, now gets **[>65M downloads/week](https://www.npmjs.com/package/json5)**, +ranks in the **[top 0.1%](https://gist.github.com/anvaka/8e8fa57c7ee1350e3491)** of the most depended-upon packages on npm, +and has been adopted by major projects like +**[Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/platform/runtime_enabled_features.json5;drc=5de823b36e68fd99009a29281b17bc3a1d6b329c), +[Next.js](https://github.com/vercel/next.js/blob/b88f20c90bf4659b8ad5cb2a27956005eac2c7e8/packages/next/lib/find-config.ts#L43-L46), +[Babel](https://babeljs.io/docs/en/config-files#supported-file-extensions), +[Retool](https://community.retool.com/t/i-am-attempting-to-append-several-text-fields-to-a-google-sheet-but-receiving-a-json5-invalid-character-error/7626), +[WebStorm](https://www.jetbrains.com/help/webstorm/json.html), +and [more](https://github.com/json5/json5/wiki/In-the-Wild)**. +It's also natively supported on **[Apple platforms](https://developer.apple.com/documentation/foundation/jsondecoder/3766916-allowsjson5)** +like **MacOS** and **iOS**. + +Formally, the **[JSON5 Data Interchange Format](https://spec.json5.org/)** is a superset of JSON +(so valid JSON files will always be valid JSON5 files) +that expands its syntax to include some productions from [ECMAScript 5.1] (ES5). +It's also a strict _subset_ of ES5, so valid JSON5 files will always be valid ES5. + +This JavaScript library is a reference implementation for JSON5 parsing and serialization, +and is directly used in many of the popular projects mentioned above +(where e.g. extreme performance isn't necessary for config file use cases), +but others have created [many other libraries](https://github.com/json5/json5/wiki/In-the-Wild) +across many other platforms. [Build Status]: https://app.travis-ci.com/json5/json5 @@ -208,18 +229,23 @@ run lint` before submitting pull requests. Please use an editor that supports [EditorConfig](http://editorconfig.org/). ### Issues -To report bugs or request features regarding the JSON5 data format, please -submit an issue to the [official specification -repository](https://github.com/json5/json5-spec). +To report bugs or request features regarding the JSON5 **data format**, +please submit an issue to the official +**[_specification_ repository](https://github.com/json5/json5-spec)**. + +Note that we will never add any features that make JSON5 incompatible with ES5; +that compatibility is a fundamental premise of JSON5. -To report bugs or request features regarding the JavaScript implementation of -JSON5, please submit an issue to this repository. +To report bugs or request features regarding this **JavaScript implementation** +of JSON5, please submit an issue to **_this_ repository**. ## License MIT. See [LICENSE.md](./LICENSE.md) for details. ## Credits [Aseem Kishore](https://github.com/aseemk) founded this project. +He wrote a [blog post](https://aseemk.substack.com/p/ignore-the-f-ing-haters-json5) +about the journey and lessons learned 10 years in. [Michael Bolin](http://bolinfest.com/) independently arrived at and published some of these same ideas with awesome explanations and detail. Recommended