docs: improve glossary for entry-point by rkirov · Pull Request #29433 · angular/angular

rkirov · 2019-03-20T21:41:13Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no api changes)
Build related changes
CI related changes
Documentation content changes
angular.io application / infrastructure changes
Other... Please describe:

rkirov · 2019-03-20T21:43:05Z

Had a bit of a debate on what to call the string 'XXX' that goes in the import statement import {...} from 'XXX';, but according to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import it is the 'module name'. I see you use module ID in your doc, but it has no other mention in the glossary. Your call.

IgorMinar · 2019-03-20T21:59:56Z

-
-Within Angular, use [NgModules](guide/glossary#ngmodule) to make public parts available for import by other NgModules.
-
+A JavaScript module(guide/glossary#module) that is indended to be imported by a user of [a npm package](guide/npm-packages). Usually, it simply reexports symbols from other internal modules. [A npm package](guide/npm-packages) can contain multiple entry-points. For example, the `@angular/core` package has two entry-point modules, which can be imported using the module names - `@angular/core` and `@angular/core/testing`.   


we might also mention that the first one is the "primary entry-point" and the /testing is a "secondary entry-point".

a package can one only zero (unusual) to one primary entry-points, and zero (common) to N secondary entry-points.

How can a consumer see the - 'primary', 'secondary' distinction? Is in the package.json?

Also is there a system to prevent imports from non-entry-point modules?

Copy-edit:
A JavaScript module(guide/glossary#module) intended for import by a user of an npm package. An entry-point module typically re-exports symbols from other internal modules. A package can contain multiple entry-points. For example, the @angular/core package has two entry-point modules, which can be imported using the module names @angular/core and @angular/core/testing.

copy-edit done. Didn't add 'primary', 'secondary', because I think it needs more clarification.

IgorMinar · 2019-03-20T22:00:50Z

-
-Within Angular, use [NgModules](guide/glossary#ngmodule) to make public parts available for import by other NgModules.
-
+A JavaScript module(guide/glossary#module) that is indended to be imported by a user of [a npm package](guide/npm-packages). Usually, it simply reexports symbols from other internal modules. [A npm package](guide/npm-packages) can contain multiple entry-points. For example, the `@angular/core` package has two entry-point modules, which can be imported using the module names - `@angular/core` and `@angular/core/testing`.   


you might also want to mention that the thing you import from a module/entry-point is a symbol and link to a definition of that (add one in this PR if a definition doesn't exist)

I am afraid that leads into a rabbit hole of JavaScript semantics - for one import {A, B} from ... imports multiple symbols. Can we expect basic ES modules knowledge?

Perhaps:
The import operation results in a Symbol value for each item imported from the entry-point module.

Unless I am mistaked, ES6 Symbols (https://developer.mozilla.org/en-US/docs/Glossary/Symbol) have nothing to do with ES6 Module names, which is another good reason not to use the word symbol when talking about modules.

IgorMinar · 2019-03-20T22:08:33Z

Had a bit of a debate on what to call the string 'XXX' that goes in the import statement import {...} from 'XXX';, but according to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import it is the 'module name'. I see you use module ID in your doc, but it has no other mention in the glossary. Your call.

We can standardize on "module name" and remove references to "module id" if we can validate that also one more place uses that terminology - e.g. TypeScript.

I think we use moduleId or id as prop name in some apis so we should weigh in the cost of renaming that. But using standard terminology is very important so we should swallow that cost if necessary as long as we plan the change well. As far as I can tell, it's just these two places and in both cases the property is about to become obsolete for unrelated reasons:

https://angular.io/api/core/NgModule - id
https://angular.io/api/core/Component - moduleId

jenniferfell · 2019-04-02T22:19:36Z

@jbogarthyde : Hi. As docs lead for the glossary work, I just wanted to make sure you have a chance to see this. Also, please help shepherd this through the process as needed. Thanks!

jbogarthyde · 2019-04-09T21:48:15Z

-
-Within Angular, use [NgModules](guide/glossary#ngmodule) to make public parts available for import by other NgModules.
-
+A JavaScript module(guide/glossary#module) that is indended to be imported by a user of [a npm package](guide/npm-packages). Usually, it simply reexports symbols from other internal modules. [A npm package](guide/npm-packages) can contain multiple entry-points. For example, the `@angular/core` package has two entry-point modules, which can be imported using the module names - `@angular/core` and `@angular/core/testing`.   


Copy-edit:
A JavaScript module(guide/glossary#module) intended for import by a user of an npm package. An entry-point module typically re-exports symbols from other internal modules. A package can contain multiple entry-points. For example, the @angular/core package has two entry-point modules, which can be imported using the module names @angular/core and @angular/core/testing.

jbogarthyde · 2019-04-09T21:51:59Z

-
-Within Angular, use [NgModules](guide/glossary#ngmodule) to make public parts available for import by other NgModules.
-
+A JavaScript module(guide/glossary#module) that is indended to be imported by a user of [a npm package](guide/npm-packages). Usually, it simply reexports symbols from other internal modules. [A npm package](guide/npm-packages) can contain multiple entry-points. For example, the `@angular/core` package has two entry-point modules, which can be imported using the module names - `@angular/core` and `@angular/core/testing`.   


Perhaps:
The import operation results in a Symbol value for each item imported from the entry-point module.

brandonroberts · 2019-05-21T13:57:03Z

@rkirov will you rebase on master?

jbogarthyde

Please make the copy-edit changes.

rkirov · 2019-05-28T17:53:55Z

Rebased and added copy-edits.

jbogarthyde

a couple of typos

jbogarthyde · 2019-05-28T17:57:10Z

indented -> intended

jbogarthyde · 2019-05-28T17:58:21Z

entry-points -> entry points
(hyphen only when used as an adjective)

jbogarthyde

One of the typos still there, sorry.

jbogarthyde · 2019-05-28T20:31:29Z

Still not corrected -- "indented" -> "intended"

lol, fixed. Thanks for being thorough.

jbogarthyde

LGTM

ngbot · 2019-05-28T21:23:10Z

I see that you just added the PR action: merge label, but the following checks are still failing:
     status "ci/circleci: test_aio" is failing
     missing required labels: PR target: *
     status "ci-codefresh-bazel" is pending
     2 pending code reviews

If you want your PR to be merged, it has to pass all the CI checks.

If you can't get the PR to a green state due to flakes or broken master, please try rebasing to master and/or restarting the CI job. If that fails and you believe that the issue is not due to your change, please contact the caretaker and ask for help.

jbogarthyde · 2019-05-28T21:23:36Z

Apparently failing because it doesn't come from a forked repo. Please help.

PR Close #29433

angular-automatic-lock-bot · 2019-09-15T03:51:25Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

rkirov requested review from a team and IgorMinar March 20, 2019 21:41

googlebot added the cla: yes label Mar 20, 2019

IgorMinar suggested changes Mar 20, 2019

View reviewed changes

matsko added the comp: docs label Mar 21, 2019

ngbot Bot added this to the needsTriage milestone Mar 21, 2019

jenniferfell requested a review from jbogarthyde April 2, 2019 22:16

jenniferfell assigned jbogarthyde Apr 2, 2019

jenniferfell added docsarea: terminology feature Label used to distinguish feature request from other issues effort2: days risk: medium labels Apr 2, 2019

ngbot Bot modified the milestones: needsTriage, Backlog Apr 2, 2019

jbogarthyde suggested changes Apr 9, 2019

View reviewed changes

brandonroberts requested review from IgorMinar and jbogarthyde May 21, 2019 13:56

jbogarthyde suggested changes May 21, 2019

View reviewed changes

rkirov force-pushed the rkirov-entry-point branch 2 times, most recently from 639eef1 to 1551920 Compare May 28, 2019 17:53

jbogarthyde suggested changes May 28, 2019

View reviewed changes

rkirov force-pushed the rkirov-entry-point branch from 1551920 to ad66716 Compare May 28, 2019 18:24

jbogarthyde suggested changes May 28, 2019

View reviewed changes

docs: improve glossary for entry-point.

8a68ec0

rkirov force-pushed the rkirov-entry-point branch from ad66716 to 8a68ec0 Compare May 28, 2019 20:35

jbogarthyde approved these changes May 28, 2019

View reviewed changes

jbogarthyde added the merge: caretaker note Alert the caretaker performing the merge to check the PR for an out of normal action needed or note label May 28, 2019

ngbot Bot added the action: merge The PR is ready for merge by the caretaker label May 28, 2019

matsko added the target: patch This PR is targeted for the next patch release label May 30, 2019

matsko closed this in a2d26c6 May 30, 2019

matsko pushed a commit that referenced this pull request May 30, 2019

docs: improve glossary for entry-point. (#29433)

31aba96

PR Close #29433

angular-automatic-lock-bot Bot locked and limited conversation to collaborators Sep 15, 2019

IgorMinar deleted the rkirov-entry-point branch June 9, 2020 20:14


		Within Angular, use [NgModules](guide/glossary#ngmodule) to make public parts available for import by other NgModules.

		A JavaScript module(guide/glossary#module) that is indended to be imported by a user of [a npm package](guide/npm-packages). Usually, it simply reexports symbols from other internal modules. [A npm package](guide/npm-packages) can contain multiple entry-points. For example, the `@angular/core` package has two entry-point modules, which can be imported using the module names - `@angular/core` and `@angular/core/testing`.

Conversation

rkirov commented Mar 20, 2019

PR Checklist

PR Type

Uh oh!

rkirov commented Mar 20, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde Apr 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IgorMinar commented Mar 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jenniferfell commented Apr 2, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde Apr 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandonroberts commented May 21, 2019

Uh oh!

jbogarthyde left a comment

Choose a reason for hiding this comment

Uh oh!

rkirov commented May 28, 2019

Uh oh!

jbogarthyde left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rkirov May 28, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbogarthyde left a comment

Choose a reason for hiding this comment

Uh oh!

ngbot Bot commented May 28, 2019

Uh oh!

jbogarthyde commented May 28, 2019

Uh oh!

angular-automatic-lock-bot Bot commented Sep 15, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jbogarthyde Apr 9, 2019 •

edited

Loading

IgorMinar commented Mar 20, 2019 •

edited

Loading

jbogarthyde Apr 9, 2019 •

edited

Loading

rkirov May 28, 2019 •

edited

Loading