From 6a41189a98e29b0c233f12610220490b6deed608 Mon Sep 17 00:00:00 2001 From: Ryan Dahl Date: Tue, 15 Jan 2019 12:28:09 -0500 Subject: [PATCH] Improve readme (#117) --- README.md | 53 +++++++++++++++++++++-------------------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3d2f1901b0..f0f3a90fc0 100644 --- a/README.md +++ b/README.md @@ -2,52 +2,41 @@ [![Build Status](https://dev.azure.com/denoland/deno_std/_apis/build/status/denoland.deno_std?branchName=master)](https://dev.azure.com/denoland/deno_std/_build/latest?definitionId=2?branchName=master) -- **[colors](./colors/)** +These modules do not have external dependencies and they are reviewed by the +Deno core team. The intention is to have a standard set of high quality code +that all Deno projects can use fearlessly. - Modules that generate ANSI color codes for the console. +Contributions are welcome! -- **[flags](./flags/)** +## How to use - Command line arguments parser. +These modules are tagged in accordance with Deno releases. So, for example, the +v0.2.6 tag is guaranteed to work with deno v0.2.6. +You can link to v0.2.6 using the URL `https://deno.land/x/std@v0.2.6/` -- **[log](./log/)** - - Command line logging - -- **[media_types](./media_types/)** - - A library for resolving media types (MIME types) and extensions. - -- **[mkdirp](./fs/)** - - Make directory branches. - -- **[http](./http/)** - - A framework for creating HTTP/HTTPS servers inspired by GoLang. - -- **[path](./fs/path)** - - File path manipulation. - -- **[testing](./testing/)** - - Testing +It's strongly recommended that you link to tagged releases rather than the +master branch. The project is still young and we expect disruptive renames in +the future. ## Style Guide +### Use TypeScript + ### Use the term "module" instead of "library" or "package" For clarity and consistency avoid the terms "library" and "package". Instead use "module" to refer to a single JS or TS file and also to refer to a directory of TS/JS code. -### Use the filename "mod.ts" as the default entry point to a directory of code +### Do not use the filename `index.ts` nor `index.js` -`index.ts` comes with the wrong connotations - and `main.ts` should be reserved -for executable programs. The filename `mod.ts` follows Rust’s convention, is -shorter than `index.ts`, and doesn’t come with any preconceived notions about -how it might work. +Deno does not treat "index.js" or "index.ts" in a special way. By using these +filenames, it suggests that they can be left out of the module specifier when +they cannot. This is confusing. + +If a directory of code needs a default entry point, use the filename `mod.ts`. +The filename `mod.ts` follows Rust’s convention, is shorter than `index.ts`, and +doesn’t come with any preconceived notions about how it might work. ### Within `deno_std`, do not depend on external code