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

HarshithaKP · 2020-02-20T07:03:30Z

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

glossary.md

joyeecheung · 2020-02-20T07:56:49Z

glossary.md

+  callable from JS.
+* primordials: Pristine built-ins that are not effected by prototype
+  pollution and tampering with built-ins.
+* snapshot: Native object code compiled from the JS APIs of Node.js


Suggested change

* snapshot: Native object code compiled from the JS APIs of Node.js

* 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.

There is also the heap snapshot BTW.

@joyeecheung, ditto.

addressed

joyeecheung · 2020-02-21T08:44:38Z

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


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.

@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

starkwang · 2020-02-21T09:27:21Z

I'm +1 on adding more information to Glossary.md but -1 on adding general words like OSX, ECMA or MDN.

HarshithaKP · 2020-02-21T09:48:30Z

@starkwang, general is a relative term right? for folks who don't know the meaning of those will also don't know where to search for it?

my general request is to look at the list from a new comer's angle, not from an experienced node.js programmer's.

joyeecheung · 2020-02-21T12:00:41Z

for folks who don't know the meaning of those will also don't know where to search for it?

I'd suggest we give links to "where to search for it" instead of trying to explain them ourselves. For example, the explanation of ABI here:

ABI: Application Binary Interface - contracts for internal API invocations.

seems misleading to me - to me API is a concept at the level of source code, which is relevant in writing programs, not in loading binaries. On the other hand Wikipedia does a better job explaining it:

An ABI defines how data structures or computational routines are accessed in machine code, which is a low-level, hardware-dependent format; in contrast, an API defines this access in source code, which is a relatively high-level, hardware-independent, often human-readable format. A common aspect of an ABI is the calling convention, which determines how data is provided as input to or read as output from computational routines; examples are the x86 calling conventions.

my general request is to look at the list from a new comer's angle, not from an experienced node.js programmer's

While I agree that the list exists to serve new comers, I don't think we need to extend the list to include terms that are not particularly different in the context of Node.js and that most people learn from elsewhere - so they are more like list for people who are new to system programming than to people who are new to Node.js itself. For instance code cache and snapshot carry special meanings in this repository, so it makes sense to include them here, while ABI or RAII doesn't - those are concepts regularly taught in courses/books/tutorials/videos/whatever about systems and/or C/C++, and it's better that people learn them from those sources instead of here (if necessary, we could list links to those sources, sure). Otherwise we end up recreating an index of terms of a textbook about system or C/C++ here, which is a good effort but IMO not an effort that belongs in this repo.

gireeshpunathil · 2020-02-21T13:04:12Z

one advantage of this approach (as opposed to linking to external sites) is, meaning can be interpreted in our usage context. example:

node/src/node_version.h

Lines 78 to 80 in 0c3c0e7

    
            * Node.js will refuse to load modules with a non-matching ABI version. The 
        
            * version number here should be changed whenever an ABI-incompatible API change 
        
            * is made in the C++ side, including in V8 or other dependencies.

here, we are not really using this term to refer to hardware architectures or subroutine linkage conventions; but to a protocol by which node interacts with the the dependent modules? so instead of taking to the general literature of its definition, history etc. a short description that will satisfy the need for some one reading through the code will be more effective?

another example:

node/src/node_options.cc

Lines 541 to 544 in 0c3c0e7

    
           AddOption("--interactive", 
        
                     "always enter the REPL even if stdin does not appear " 
        
                     "to be a terminal", 
        
                     &EnvironmentOptions::force_repl);

here, the reader may not want to know the complete story of https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop - as at that point they may not be interested in that; but just to fill the gap of their understanding (a simple expansion) and move on with the option parsing?

we do have precedence here in https://github.com/nodejs/node/blob/0c3c0e7184c4ca625148c14d61d8e9438a1b69f2/CPP_STYLE_GUIDE.md as well as https://github.com/nodejs/node/blob/0c3c0e7184c4ca625148c14d61d8e9438a1b69f2/src/README.md that provide customized knowledge on C++ usage in the code base.

and technically too I find this approach correct - sticking to the definition of glossary: a brief dictionary of used words that are uncommon.

joyeecheung · 2020-02-22T14:49:35Z

@gireeshpunathil I agree that providing customized knowledge about these terms in the context of Node.js would be useful (for example, by REPL we mean "the thing you see when you run node in the terminal") , even for people who understand the general meaning of those terms but do not know how or when these become relevant in this codebase. However by putting things into context it would go against the goal of keeping the dictionary brief. For example, IMO if you do not know what ABI or RAII is, expanding them to Application Binary Interface or Resource Aquisition Is Intialization is still not sufficient for you to understand the comments mentioning them and keep reading/editing the code. To put those terms into the context of Node.js we need to explain by giving examples. Also, that's not what this PR is doing right now - it is giving general explanations about these terms.

glossary.md

HarshithaKP · 2020-02-24T11:14:50Z

@joyeecheung and @gengjiawen , addressed your concerns by removing explanation and providing external links wherever it is applicable. Please have a look and let me know if you are good with that.

HarshithaKP · 2020-02-26T08:03:52Z

@gengjiawen -

gengjiawen self-requested a review 2 days ago

did you mean to keep this for your review-todo list,

or

did you mean to dismiss your earlier change-request?

gengjiawen · 2020-02-26T08:26:49Z

@gengjiawen -

gengjiawen self-requested a review 2 days ago

did you mean to keep this for your review-todo list,

or

did you mean to dismiss your earlier change-request?

I mean to dismiss your earlier change-request.

Also I am -1 on adding MDN MAC and RAII such C++ staff.

HarshithaKP · 2020-02-26T09:25:02Z

@gengjiawen, can you please explain your reason? Is it that you think those do not need explanation, or thier explanations are not accurate?

glossary.md

joyeecheung

Why are some terms expanded with further explanations while some are only expanded? What's the reasoning behind that?

joyeecheung · 2020-03-09T21:54:41Z

glossary.md

+* CJS: Common JS.
+* CLDR: Common Locale Data Repository.
+* CLI: [Command Line Interface](https://en.wikipedia.org/wiki/Command-line_interface)
+* CMD: Command.


This is not a widely used word AFAIK?

Removed it.

joyeecheung · 2020-03-09T21:56:02Z

glossary.md

+  maintains reported security exposures.
+* ECMA: European Computer Manufacturers Association - A body that
+  governs JS spec among other things.
+* ENV: Environment - General term for execution environment.


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.

Removed it.

joyeecheung · 2020-03-09T21:57:25Z

glossary.md

+  (when used within project documents).
+* ESM: ECMA Script Module.
+* ETW: Event Tracing for Windows.
+* FD: File Descriptor.


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)

Removed it.

joyeecheung · 2020-03-09T21:59:31Z

glossary.md

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


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

Thanks, changed it.

joyeecheung · 2020-03-09T22:10:45Z

glossary.md

+* IPC: Inter Process Communication.
+* JIT: Just In Time - General term for dynamic compiler in
+  managed runtimes.
+* JS/C++ boundary: A layer that bridges between JS APIs and the C++


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.

Thanks, Changed it. PTAL.

joyeecheung · 2020-03-09T22:22:43Z

glossary.md

-* 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.
+* VM: Virtual Machine, in the context of abstracting instructions,


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.

Thanks, changed it accordingly and linked it. PTAL.

joyeecheung · 2020-03-09T22:24:04Z

glossary.md

+  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


Why not link to it directly?

Thanks, linked it.

joyeecheung · 2020-03-09T22:27:10Z

glossary.md

+* ASYNC: Asynchronous
+* BE: Big Endian - Byte order style in a multibyte data.
+  (Opposite of LE, Little Endian)
+* CI: Continuous Integration.


This does not seen to be useful for people who don't know what CI is

Linked it to Wikipedia explanation.

joyeecheung · 2020-03-09T22:28:31Z

glossary.md

-* RSLGTM: "Rubber-stamp looks good to me". The reviewer approving without doing
+* ABI: [Application Binary Interface](https://en.wikipedia.org/wiki/Application_binary_interface)
+* ASAP: As Soon As Possible.
+* ASYNC: Asynchronous


Why is SYNC left out if ASYNC needs explanation?

Removed it.

joyeecheung · 2020-03-09T22:28:52Z

glossary.md

+* CITGM: Canary In The Gold Mine - a smoke test unit in the repo that
+  contain popular npm modules.
+* CJS: Common JS.
+* CLDR: Common Locale Data Repository.


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

Thanks, linked it to Wikipedia explanation.

HarshithaKP · 2020-05-18T09:50:04Z

@joyeecheung, Can you please take a look at my changes. I tried addressing most of your review comments.

jasnell · 2020-07-03T21:24:53Z

Ping @joyeecheung

mhdawson

LGTM

gireeshpunathil · 2021-07-27T03:35:58Z

one more ping to @joyeecheung
@HarshithaKP - can you pls rebase to resolve the file conflict?

HarshithaKP · 2021-07-27T05:18:34Z

@gireeshpunathil sure

RedYetiDev · 2024-04-21T14:40:13Z

Hi! It's been a few years since any activity on this PR.

If you're still interested in pursuing this, I suggest verifying that everything is still in working order after the long delay. Otherwise, you can always close the PR.

Nonetheless, your contribution is greatly appreciated!

This is an attempt to resolve older PRs and issues

@nodejs/documentation

gireeshpunathil · 2024-04-21T14:45:16Z

IMO, the info will be really useful especially for new comers, but the current form needs updates and validations.

RedYetiDev · 2024-04-21T14:53:06Z

IMO, the info will be really useful especially for new comers, but the current form needs updates and validations.

Agreed, but it might need a separate PR, as there have been a significant number of changes to the project since this PR.

@HarshithaKP do you still want to pursue this? A member of the team can also take over if you’d like.

gireeshpunathil · 2024-04-21T16:31:13Z

I reviewed the change set now, and looks all valid to me. So if there are no objections and file rebased, it is ready to merge.

one lingering comment is why some of this can be found through general knowledge base such as google. Problem with wide search is lack of personalisation. For example when I searched "EOL" I got "EXTRA ORDINARY LEAVE". Here we are explaining the terms in context and that is largely beneficial to new comers.

@joyeecheung - do you have any observations?

RedYetiDev · 2024-04-21T16:40:20Z

Great! I'm glad everything is still not conflicting!

RedYetiDev

Few little nitpicks, but otherwise LGTM

RedYetiDev · 2024-04-21T16:41:35Z

glossary.md

+* CJS: Common JS.
+* CLDR: [Common Locale Data Repository](https://en.wikipedia.org/wiki/Common_Locale_Data_Repository).
+* CLI: [Command Line Interface](https://en.wikipedia.org/wiki/Command-line_interface).
+* CVE: Common Vulnerebilities and Exposures - A database that


(Typo) CVE: Common Vulnerabilities and Exposures

RedYetiDev · 2024-04-21T16:42:13Z

glossary.md

+* ETW: Event Tracing for Windows.
+* 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.


Double spacing is not needed

joyeecheung

Sorry for missing the pings, probably got lost during the hectic zero-COVID days..

joyeecheung · 2024-04-21T20:23:54Z

glossary.md

+* CI: [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration).
+* CITGM: Canary In The Gold Mine - a smoke test unit in the repo that
+  contain popular npm modules.
+* CJS: Common JS.


Suggested change

* CJS: Common JS.

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

joyeecheung · 2024-04-21T20:24:27Z

glossary.md

+* EOF: [End Of File](https://en.wikipedia.org/wiki/End-of-file)
+* EOL: End Of Line (when used within a program), End of Life
+  (when used within project documents).
+* ESM: ECMA Script Module.


Suggested change

* ESM: ECMA Script Module.

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

joyeecheung · 2024-04-21T20:26:30Z

glossary.md

+  of a program `at run time` rather than before execution.
+* JS/C++ boundary: It refers  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). The boundary could very well exist when we


Suggested change

C++ linkage (e.g. interceptors). The boundary could very well exist when we

C++ linkage (e.g. `v8::FunctionCallback`). The boundary exist when we

interceptors are only very rarely used. v8::FunctionCallbacks are a lot more common.

joyeecheung · 2024-04-21T20:28:02Z

glossary.md

+* CVE: Common Vulnerebilities and Exposures - A database that
+  maintains reported security exposures.
+* ECMA: European Computer Manufacturers Association - A body that
+  governs JS spec among other things.


Suggested change

governs JS spec among other things.

governs the specification of the JavaScript language, among other things.

RedYetiDev · 2024-05-05T21:38:05Z

Moved to #52798. The original author is the Co-Author.

doc: Add more useful information to Glossary.md

82cefbd

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Feb 20, 2020

joyeecheung previously requested changes Feb 20, 2020

View reviewed changes

fixup: address review comments

7524866

joyeecheung reviewed Feb 21, 2020

View reviewed changes

fixup: address review comments

161016e

gengjiawen reviewed Feb 24, 2020

View reviewed changes

glossary.md Outdated Show resolved Hide resolved

gengjiawen requested changes Feb 24, 2020

View reviewed changes

glossary.md Outdated Show resolved Hide resolved

fixup: address review comments

9e59376

gengjiawen self-requested a review February 24, 2020 11:16

joyeecheung reviewed Feb 26, 2020

View reviewed changes

glossary.md Outdated Show resolved Hide resolved

fixup: address review comment

c6c9891

gireeshpunathil approved these changes Feb 27, 2020

View reviewed changes

BridgeAR approved these changes Mar 9, 2020

View reviewed changes

joyeecheung reviewed Mar 9, 2020

View reviewed changes

fixup: address review comments

0d94c6e

BridgeAR force-pushed the master branch 2 times, most recently from 8ae28ff to 2935f72 Compare May 31, 2020 12:19

mhdawson approved these changes Jul 3, 2020

View reviewed changes

guybedford force-pushed the master branch from dc5a5da to 8e46568 Compare March 29, 2021 21:33

Trott force-pushed the main branch from 2d76238 to ca3ed36 Compare November 12, 2022 01:49

RedYetiDev reviewed Apr 21, 2024

View reviewed changes

joyeecheung approved these changes Apr 21, 2024

View reviewed changes

aymen94 approved these changes Apr 22, 2024

View reviewed changes

RedYetiDev added the meta Issues and PRs related to the general management of the project. label Apr 22, 2024

RedYetiDev mentioned this pull request May 2, 2024

doc: add more definitions to GLOSSARY.md #52798

Merged

RedYetiDev closed this May 5, 2024

-* snapshot: Native object code compiled from the JS APIs of Node.js
+* 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.

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

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

	C++ linkage (e.g. interceptors). The boundary could very well exist when we
	C++ linkage (e.g. `v8::FunctionCallback`). The boundary exist when we

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

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

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

Conversation

HarshithaKP commented Feb 20, 2020

Checklist

joyeecheung Feb 20, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung Feb 21, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

starkwang commented Feb 21, 2020

HarshithaKP commented Feb 21, 2020

joyeecheung commented Feb 21, 2020 • edited

gireeshpunathil commented Feb 21, 2020

joyeecheung commented Feb 22, 2020 • edited

HarshithaKP commented Feb 24, 2020

HarshithaKP commented Feb 26, 2020

gengjiawen commented Feb 26, 2020

HarshithaKP commented Feb 26, 2020

joyeecheung left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung Mar 9, 2020 • edited

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

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

HarshithaKP commented May 18, 2020

jasnell commented Jul 3, 2020

mhdawson left a comment

Choose a reason for hiding this comment

gireeshpunathil commented Jul 27, 2021

HarshithaKP commented Jul 27, 2021

RedYetiDev commented Apr 21, 2024

gireeshpunathil commented Apr 21, 2024

RedYetiDev commented Apr 21, 2024

gireeshpunathil commented Apr 21, 2024

RedYetiDev commented Apr 21, 2024

RedYetiDev left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung left a 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

RedYetiDev commented May 5, 2024

joyeecheung Feb 20, 2020 •

edited

joyeecheung Feb 21, 2020 •

edited

joyeecheung commented Feb 21, 2020 •

edited

joyeecheung commented Feb 22, 2020 •

edited

joyeecheung Mar 9, 2020 •

edited