Skip to content
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.

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

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

Closed
wants to merge 6 commits into from

Conversation

HarshithaKP
Copy link
Member

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

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Feb 20, 2020
glossary.md Outdated Show resolved Hide resolved
glossary.md Outdated
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
Copy link
Member

@joyeecheung joyeecheung Feb 20, 2020

Choose a reason for hiding this comment

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

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.

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, ditto.

glossary.md Outdated
* 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

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

@starkwang
Copy link
Contributor

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

@HarshithaKP
Copy link
Member Author

@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
Copy link
Member

joyeecheung commented Feb 21, 2020

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
Copy link
Member

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
Copy link
Member

joyeecheung commented Feb 22, 2020

@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 Outdated Show resolved Hide resolved
glossary.md Outdated Show resolved Hide resolved
@HarshithaKP
Copy link
Member Author

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

@gengjiawen gengjiawen self-requested a review February 24, 2020 11:16
@HarshithaKP
Copy link
Member Author

@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
Copy link
Member

@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
Copy link
Member Author

@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 Outdated Show resolved Hide resolved
Copy link
Member

@joyeecheung joyeecheung left a comment

Choose a reason for hiding this comment

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

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

glossary.md Outdated
* CJS: Common JS.
* CLDR: Common Locale Data Repository.
* CLI: [Command Line Interface](https://en.wikipedia.org/wiki/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.

glossary.md Outdated
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.
Copy link
Member

@joyeecheung joyeecheung Mar 9, 2020

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.

glossary.md Outdated
(when used within project documents).
* ESM: ECMA Script Module.
* 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.

glossary.md Outdated
* 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.

glossary.md Outdated
* 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++
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.

glossary.md Outdated
* 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,
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.

glossary.md Outdated
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.

glossary.md Outdated
* ASYNC: Asynchronous
* BE: Big Endian - Byte order style in a multibyte data.
(Opposite of LE, Little Endian)
* CI: Continuous Integration.
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 seen to be useful for people who don't know what CI 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.

Linked it to Wikipedia explanation.

glossary.md Outdated
* 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
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.

glossary.md Outdated
* 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.
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.

@HarshithaKP
Copy link
Member Author

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

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

jasnell commented Jul 3, 2020

Ping @joyeecheung

Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

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

LGTM

@gireeshpunathil
Copy link
Member

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

@HarshithaKP
Copy link
Member Author

@gireeshpunathil sure

@RedYetiDev
Copy link
Member

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
Copy link
Member

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

@RedYetiDev
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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

Copy link
Member

@RedYetiDev RedYetiDev left a comment

Choose a reason for hiding this comment

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

Few little nitpicks, but otherwise LGTM

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

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

Copy link
Member

@joyeecheung joyeecheung left a comment

Choose a reason for hiding this comment

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

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

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

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

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

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

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

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

@RedYetiDev RedYetiDev closed this May 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Development

Successfully merging this pull request may close these issues.