docs(website/manual): Manual introduction improvements #3157

andyfleming · 2019-10-19T22:28:59Z

This reorganizes and improves some of the introduction content.

This is just a first pass, but I think it's an extremely important part of the experience for newcomers to the project.

@ry @kitsonk — This is related to some of the conversations we had at TSConf. I'd love to get your thoughts on these changes.

I've put some comments inline in the PR to help explain some of the specific changes.

CLAassistant · 2019-10-19T22:29:23Z

All committers have signed the CLA.

andyfleming · 2019-10-19T22:29:56Z

website/manual.md


-Deno aims to be a productive and secure scripting environment for the modern
-programmer.
+## Project Status / Disclaimer


Calling this "Project Status" makes it a little friendlier.

andyfleming · 2019-10-19T22:30:08Z

website/manual.md

-Deno provides <a href="https://github.com/denoland/deno/tree/master/std">a set
-of reviewed (audited) standard modules</a> that are guaranteed to work with
-Deno.
+We are [actively working towards 1.0](https://github.com/denoland/deno/issues/2473), but there is no date guarantee.


Adds a link for those who want to follow the latest on 1.0.

andyfleming · 2019-10-19T22:31:05Z

website/manual.md


- Uses "ES Modules" and does not support `require()`. Like the browser, allows
-  imports from URLs:
+It's built on V8, Rust, and Tokio.


I think it's a little weird to call it a "secure runtime". "Secure defaults" feels more accurate and to the point. It also leaves less room for argument.

I also added that it has a "great developer experience". I don't think this has historically been a first-class goal, but I think it's in alignment with the project and is part of where we provide value.

I also purposely separated the note about what it's built on. It's somewhat relevant, but it's not the purpose of the project.

andyfleming · 2019-10-19T22:31:53Z

website/manual.md

-  import * as log from "https://deno.land/std/log/mod.ts";
-  ```
+### Feature Highlights

- Remote code is fetched and cached on first execution, and never updated until
-  the code is run with the `--reload` flag. (So, this will still work on an
-  airplane. See `~/.deno/src` for details on the cache.)
+* Secure by default. No file, network, or environment access (unless explicitly enabled).
+* Supports TypeScript out of the box.
+* Ships a single executable (`deno`).
+* Has built in utilities like a dependency inspector (`deno info`) and a code formatter (`deno fmt`).
+* Has [a set of reviewed (audited) standard modules](https://github.com/denoland/deno/tree/master/std) that are guaranteed to work with Deno.
+* Scripts can be bundled into a single javascript file.

- File system and network access can be controlled in order to run sandboxed
-  code. Access between V8 (unprivileged) and Rust (privileged) is only done via
-  serialized messages. This makes it easy to audit. For example, to enable write
-  access use the flag `--allow-write` or for network access `--allow-net`.
+##### On the Roadmap

- Only ship a single executable.
+* Native modules in Rust.
+* Scripts can be bundled into a binary with the deno runtime.
+  * This makes distribution simple and script startup very fast.


I created a new section called "Feature Highlights" which helps clean up some of the items in the goal section that weren't really goals per se.

I also think this is an important spot to pitch newcomers on our key features.

I added "Native modules in Rust" because I believe that's a goal and it's 🔥.

I added "Scripts can be bundled into a binary with the deno runtime" because it's also a feature we are pursuing and is a great differentiator.

andyfleming · 2019-10-19T22:32:07Z

website/manual.md


- Be able to serve HTTP efficiently.
-  ([Currently it is relatively slow.](https://deno.land/benchmarks.html#req-per-sec))
+Among other things, Deno is a great replacement for utility scripts that may have been historically written with bash or python.


I added this note about utility scripts. It's something that we discussed in person and I think really helps the reader understand where Deno could be really useful.

andyfleming · 2019-10-19T22:33:20Z

website/manual.md

+   * Unless specifically allowed, scripts can't access files, the environment, or the network.
+3. Browser compatible: The subset of Deno programs which are written completely in JavaScript and do not use the global `Deno` namespace (or feature test for it), ought to also be able to be run in a modern web browser without change.
+4. Be able to serve HTTP efficiently
+5. Provide a great developer experience include built-in tooling.


This is clean up a bit.

andyfleming · 2019-10-19T22:33:43Z

website/manual.md

+3. Browser compatible: The subset of Deno programs which are written completely in JavaScript and do not use the global `Deno` namespace (or feature test for it), ought to also be able to be run in a modern web browser without change.
+4. Be able to serve HTTP efficiently
+5. Provide a great developer experience include built-in tooling.
+6. Does not leak browser or V8 concepts into user land.


This goal is new, but I thought it was worth discussing.

#3158 is related in that sense.

andyfleming · 2019-10-19T22:34:10Z

website/manual.md

+### Comparison to Node.js
+
+* Deno does not use `npm`
+  * It uses modules referenced as URLs or file paths
+* Deno does not use a `package.json`
+  * This is a non-goal. There are effective patterns [citation needed] for managing dependencies.
+* Deno provides different APIs than node.
+* Deno requires explicit permissions for file, network, and environment access.
+  * Node is less secure out of the box.
+* Deno always dies on uncaught errors.
+* Uses "ES Modules" and does not support `require()`. Like the browser, allows imports from URLs:

-<!-- prettier-ignore-end -->
+```ts
+import * as log from "https://deno.land/std/log/mod.ts";
+```


I think we dance around this too much. I know we may not want to compare directly to node in some ways, but the reality is that just about everyone who comes to this project will ask about this. Let's address it as clearly and concisely as possible.

andyfleming · 2019-10-19T22:34:34Z

website/manual.md

+## Built-in Deno Utilities / Commands

- Not explicitly compatible with Node.
+ * dependency inspector (`deno info`)
+  * code formatter (`deno fmt`),
+  * bundling (`deno bundle`)
+  * runtime type info (`deno types`)
+  * test runner (`deno test`)
+  * command-line debugger (`--debug`) [coming soon](https://github.com/denoland/deno/issues/1120)
+    * linter (`deno lint`) [coming soon](https://github.com/denoland/deno/issues/1880)


This section was split out from above so the above contents can be more concise.

andyfleming · 2019-10-19T22:35:34Z

website/manual.md

+### Other key behaviors

- No `package.json`.
+* Remote code is fetched and cached on first execution, and never updated until the code is run with the `--reload` flag. (So, this will still work on an airplane. See `~/.deno/src` for details on the cache.)
+* Modules/files loaded from remote URLs are intended to be immutable and cacheable.


I'm not sure if this is the right home for these points, but I didn't want to delete them.

I also added the note about immutable intention which @kitsonk and I talked about a bit. It's an opinionated proposal, but worth discussing.

Also mentioned this in #3158

ry · 2019-10-19T22:45:40Z

Please run tools/format.py

andyfleming · 2019-10-19T22:56:52Z

@ry It's not super clear the workflow for running tools/format.py. I checked the contribution guide but it didn't help much. I'll open a PR for that next 😂.

I ran yarn at the top level but I still get this error when running tools/format.py --js.

prettier
internal/modules/cjs/loader.js:797
    throw err;
    ^

Error: Cannot find module '/Users/user/code/deno/third_party/node_modules/prettier/bin-prettier.js'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:794:15)
    at Function.Module._load (internal/modules/cjs/loader.js:687:27)
    at Function.Module.runMain (internal/modules/cjs/loader.js:1025:10)
    at internal/main/run_main_module.js:17:11 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

I'm sure I'm missing something simple, but some guidance would be helpful.

ry · 2019-10-19T22:59:44Z

Is the third_party directory empty? Then maybe you need to run git submodule update —init
Or something similar..

website/manual.md

andyfleming · 2019-10-19T23:08:01Z

Ah, yes my third_party directory is empty.

git submodule update --init did the trick 👍

website/manual.md

hayd · 2019-10-20T02:17:47Z

website/manual.md

- No npm.
-
- Not explicitly compatible with Node.
+- Modules/files loaded from remote URLs are intended to be immutable and


I wonder if this is actually a bug, and cache control should be respected? 😳

I was talking with @kitsonk about this. I was saying that I think it should be treated as immutable by default to encourage the practice in the community, but I think since putting a bit more thought to it, I think respecting cache headers would be fine. It doesn't prevent immutability from being possible and a best practice in the community.

I think immutability in dependencies matters for a number of reasons, but especially because Deno is striving to be security minded.

One other approach we could use would be something like subresource integrity where we could at least warn the user that a file has changed.

Regardless, I'll probably end up removing this bullet point from this PR and opening it in a separate issue for discussion.

It looks like subresource integrity has actually been brought up before in #200.

Co-Authored-By: Nayeem Rahman <[email protected]>

andyfleming · 2019-10-20T20:29:59Z

website/manual.md

-  in JavaScript and do not use the global `Deno` namespace (or feature test for
-  it), ought to also be able to be run in a modern web browser without change.
-
- [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471)


Forgot to mention that I purposely deleted this since it's (most likely) going to be standard in javascript anyway.

Co-Authored-By: Nayeem Rahman <[email protected]>

ry

Thanks !

First pass at manual introduction changes

c4655ce

andyfleming commented Oct 19, 2019

View reviewed changes

nayeemrmn reviewed Oct 19, 2019

View reviewed changes

website/manual.md Outdated Show resolved Hide resolved

andyfleming added 2 commits October 19, 2019 16:08

Removes duplicated content

35b56f8

Formats with prettier

b0355c5

nayeemrmn reviewed Oct 19, 2019

View reviewed changes

website/manual.md Outdated Show resolved Hide resolved

nayeemrmn requested changes Oct 19, 2019

View reviewed changes

website/manual.md Outdated Show resolved Hide resolved

website/manual.md Outdated Show resolved Hide resolved

hayd reviewed Oct 20, 2019

View reviewed changes

andyfleming and others added 2 commits October 19, 2019 19:26

removes unnecessary comma

149c08b

Co-Authored-By: Nayeem Rahman <[email protected]>

Removes indent

1f98d1a

andyfleming changed the title ~~First pass at manual introduction changes~~ docs(website/manual): Manual introduction improvements Oct 20, 2019

andyfleming added 2 commits October 19, 2019 20:16

Fixes formatting for bullets with coming soon links

67bab05

Fixes prettier ignore

9baab30

andyfleming commented Oct 20, 2019

View reviewed changes

andyfleming and others added 6 commits October 20, 2019 13:40

Removes outdated note

abb745d

Co-Authored-By: Nayeem Rahman <[email protected]>

fixes formatting

96b3789

Merge branch 'master' into manual-intro-changes

cc52b95

edit

406e95e

edit

ae90ec9

edit

1688b82

ry approved these changes Oct 21, 2019

View reviewed changes

ry merged commit 2b2868b into denoland:master Oct 21, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(website/manual): Manual introduction improvements #3157

docs(website/manual): Manual introduction improvements #3157

andyfleming commented Oct 19, 2019 •

edited

Loading

CLAassistant commented Oct 19, 2019 •

edited

Loading

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

andyfleming Oct 19, 2019

ry commented Oct 19, 2019

andyfleming commented Oct 19, 2019

ry commented Oct 19, 2019

andyfleming commented Oct 19, 2019

hayd Oct 20, 2019

andyfleming Oct 20, 2019 •

edited

Loading

andyfleming Oct 20, 2019

andyfleming Oct 20, 2019

ry left a comment

docs(website/manual): Manual introduction improvements #3157

docs(website/manual): Manual introduction improvements #3157

Conversation

andyfleming commented Oct 19, 2019 • edited Loading

CLAassistant commented Oct 19, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ry commented Oct 19, 2019

andyfleming commented Oct 19, 2019

ry commented Oct 19, 2019

andyfleming commented Oct 19, 2019

Choose a reason for hiding this comment

andyfleming Oct 20, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ry left a comment

Choose a reason for hiding this comment

andyfleming commented Oct 19, 2019 •

edited

Loading

CLAassistant commented Oct 19, 2019 •

edited

Loading

andyfleming Oct 20, 2019 •

edited

Loading