Skip to content

doc: Add more useful information to Glossary.md #31879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

doc: Add more useful information to Glossary.md #31879

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
82cefbd
doc: Add more useful information to Glossary.md
HarshithaKP Feb 20, 2020
7524866
fixup: address review comments
HarshithaKP Feb 20, 2020
161016e
fixup: address review comments
HarshithaKP Feb 24, 2020
9e59376
fixup: address review comments
HarshithaKP Feb 24, 2020
c6c9891
fixup: address review comment
HarshithaKP Feb 27, 2020
0d94c6e
fixup: address review comments
HarshithaKP May 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 78 additions & 10 deletions glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,84 @@
You may also need to check https://chromium.googlesource.com/chromiumos/docs/+/master/glossary.md.

* LGTM: "Looks good to me", commonly used to approve a code review.
* PTAL: Please take a look.
* RSLGTM: "Rubber-stamp looks good to me". The reviewer approving without doing
* ABI: Application Binary Interface - contracts for internal
Copy link
Member

@joyeecheung joyeecheung Feb 21, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really need entries that can be easily looked up in Wikipedia or OS textbooks and widely used in the software world in general? The same goes to things like CLI, EOF, EOL, RAII, etc. It seems we should reference a dictionary specifically for those lingos instead of listing them here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joyeecheung, (a) the problem this gloassry addresses is difficulty in discovering meaning of abbreveations, and solution is to keep those in one place for easy reference; based on our usage of those, not based on how trivial those are? (b) I did a grep in the code base and found repeated usage of these, (c) these items were proposed in the original issue by maintainers

API invocations.
* ASAP: As Soon As Possible.
* ASM: Assembler - General term for language translator, especially
from high level to low level.
* ASYNC: Asynchronous
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is SYNC left out if ASYNC needs explanation?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed it.

* BE: Big Endian - Byte order style in a multibyte data.
(Opposite of LE, Little Endian)
* CI: Continues Intigration.
* CITGM: Canary In The Gold Mine - a smoke test unit in the repo that
contain popular npm modules.
* CJS: Common JS.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* CJS: Common JS.
* CJS: CommonJS. In most cases, [CommonJS Modules](https://nodejs.org/api/modules.html#modules-commonjs-modules).

* CLDR: Common Locale Data Repository.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not seem to be useful for people who don't know what CLDR is

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, linked it to Wikipedia explanation.

* CLI: Command Line Interface.
* CMD: Command.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a widely used word AFAIK?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed it.

* CVE: Common Vulnerebilities and Exposures - A database that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Typo) CVE: Common Vulnerabilities and Exposures

maintains reported security exposures.
* ECMA: European Computer Manufacturers Association - A body that
governs JS spec among other things.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
governs JS spec among other things.
governs the specification of the JavaScript language, among other things.

* ENV: Environment - General term for execution environment.
Copy link
Member

@joyeecheung joyeecheung Mar 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are multiple explanations to Env (e.g. it's also commonly used for environment variables) and we don't usually use it in full-caps either way unless in variable names. This also does not explain what execution environment is.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed it.

* EOF: End Of File.
* EOL: End Of Line (when used within a program), End of Life
(when used within project documents).
* ESM: ECMA Script Module.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* ESM: ECMA Script Module.
* ESM: [ECMAScript Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules)

* ETW: Event Tracing for Windows.
* FD: File Descriptor.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we usually use fd other than in variable names that we want to keep short (and in that case you can easily find it out by looking at the API docs instead of this doc)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed it.

* FFDC: First Failure Data Capture - Common terms for logs, traces
and dumps that are produced by default on program error.
* FIPS: Federal Information Processing Standards.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double spacing is not needed

* FS: File System.
* ICU: International Components for Unicode.
* IPC: Inter Process Communication.
* JIT: Just In Time - General term for dynamic compiler in
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's a general term, and General term for dynamic compiler in managed runtimes seems to lead to more questions regarding "what's a dynamic compiler?" "what are managed runtimes?". I'd suggest just linking to https://en.wikipedia.org/wiki/Just-in-time_compilation and use its description

is a way of executing computer code that involves compilation during execution of a program – at run time – rather than before execution

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, changed it.

managed runtimes.
* JS/C++ boundary: A layer that bridges between JS APIs and the C++
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think is accurate - when we talk about JS/C++ boundary we are usually referring to the boundary between V8's runtime and the JS code execution which are commonly crossed when invoking JS functions with C++ linkage (e.g. interceptors), i.e. something like this

    frame #11: 0x00000001009703db node`Builtins_InterpreterEntryTrampoline + 187
    frame #12: 0x00000001009703db node`Builtins_InterpreterEntryTrampoline + 187
    frame #13: 0x00000001009703db node`Builtins_InterpreterEntryTrampoline + 187
    frame #14: 0x000000010096dfda node`Builtins_JSEntryTrampoline + 90
    frame #15: 0x000000010096ddb8 node`Builtins_JSEntry + 120

Instead of the conceptual layer in the implementation that abstracts platform capabilities. The boundary could very well exist when we are reaching into the C++ to do something that has nothing to do with the platform, e.g. URL parsing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Changed it. PTAL.

helpers that implements / abstracts platform capabilities.
* LGTM: Looks good to me - commonly used to approve a code review.
* LTS: Long Term Support.
* MDN: Mozila Development Network - A vast and authentic
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not link to it directly?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, linked it.

documentation on JavaScript.
* OOB: Out Of Bounds - Used in the context of TCP data transport.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is where OOB is mostly used - we primarily talk about OOB in array(memory) access

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed it according to suggestion. PTAL

* OOM: Out Of Memory.
* OSX: Mac OS.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This entry seems somewhat odd - why assume more people know about macOS than OS X? And it doesn't seem right to me for us to explain about Apple's branding strategy here

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed it.

* PPC: Power PC.
* PTAL: Please Take A Look.
* RAII: Resource Aquisition Is Intialization - A C++ feature for
auto-cleanup of dynamically allocated objects.
* REPL: Read Evaluate Print Loop.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not really explain what it is in the context of Node.js - I think people who don't know what REPL might still be puzzled after reading this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explained it. PTAL.

* RFC: Request For Comments.
* RSLGTM: Rubber-Stamp Looks Good To Me. The reviewer approving without doing
a full code review.
* RSS: Resident Set Size.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not seem to be meaningful to just expand the word. A link to https://en.wikipedia.org/wiki/Resident_set_size would be more useful

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Linked it.

* SMP: Symmetric Multi Processor.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this used? I don't recall seeing anyone talking about this in Node.js.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not used. Removed it.

* TSC: Technical Steering Committee. Detailed info see
[TSC](./GOVERNANCE.md#technical-steering-committee).
* WIP: "Work In Progress" - e.g. a patch that's not finished, but may be worth
an early look.
* V8: JavaScript engine that is embedded in Node.js.
Copy link
Member

@joyeecheung joyeecheung Mar 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems somewhat funny to define V8 as JavaScript engine that is embedded in Node.js which may send you the impression (provided that you don't know what it is) that this is a code name for a component developed for Node.js

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed the definition, PTAL.

* VM: Virtual Machine, in the context of abstracting instructions,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think in this code base the most commonly used meaning of vm is actually the vm builtin module, which is not really a Virtual Machine but just an unfortunate name for something it is not..and describing VM this way does not seem to help clarifying that misconceptioin.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, changed it accordingly and linked it. PTAL.

not to be confused with H/W level or O/S level Virtual machines.
* WASI: Web Assemby System Interface.
* WASM: Web Assembly.
* WG: Working Group - autonomous teams in the project with specific
focus areas.
* WHATWG: Web Hypertext Application Technology Working Group
* WIP: "Work In Progress" - e.g. a patch that's not finished, but
may be worth an early look.
* WPT: [web-platform-tests](https://github.com/web-platform-tests/wpt)
* godbolt: [Compiler Explorer](https://godbolt.org/) run compilers interactively
from your web browser and interact with the assembly. Was created by and is
primarily administrated by Matt Godbolt.
* primordials: Pristine built-ins that are not effected by prototype pollution
and tampering with built-ins.
* bootstrap: Early phase in the Node.js process startup - that sets up
the Node.js execution environment and loads the internal modules.
* code cache: A chunk of bytes storing compiled JS code and its metadata.
* deps: upstream projects that this project depends.
* godbolt: [Compiler Explorer](https://godbolt.org/) run compilers
interactively from your web browser and interact with the assembly.
Was created by and is primarily administrated by Matt Godbolt.
* native modules/addons: A module / shared library that is
implemented in C/C++, but exposes one or more interfaces,
callable from JS.
* primordials: Pristine built-ins that are not effected by prototype
pollution and tampering with built-ins.
* snapshot: When referring to the V8 startup snapshot, a chunk of
bytes containing data serialized from a V8 heap, which can be
deserialized to restore the states of the V8 engine.
* vendoring: consuming external software into this project.