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

about_Scopes is missing an important concept: internal "session states" #4288

Open
mklement0 opened this issue May 9, 2019 · 2 comments

Comments

Projects
None yet
3 participants
@mklement0
Copy link
Contributor

commented May 9, 2019

There are distinct "scope domains", called "session states" in the source code, that make up a single PowerShell session, as explained in this excellent blog post by @SeeminglyScience.

Documenting these in about_Scopes and giving them a descriptive official name is important.

The summary is:

  • All non-module code runs in a hierarchy of scopes whose root scope is the one and only global scope.

  • All module code runs in a module-specific hierarchy of scopes that has its own root scope.

    • However, the global scope's definitions are still visible in module code.

In other words: the only shared ancestral scope whose definitions are visible to both module and non-module code is the global scope.

I propose not calling these distinct scope hierarchies session states, because the latter suggests a concept relating to a session as a whole, which is confusing. Additionally, global session state is confusing, because only its root scope is truly global. Finally, it is confusing that the word scope is not in the name at all.

(As far as I know, the concepts aren't currently explained anywhere, but the confusing terms are used in https://docs.microsoft.com/en-us/powershell/developer/module/how-to-write-a-powershell-module-manifest)

I propose the term scope domain for these distinct scope hierarchies, but that is open to debate:

  • The global "session state" would be called default scope domain.
  • Module-specific "session states" would be called module scope domains.

@SeeminglyScience has voiced concerns in PowerShell/PowerShell#8988 (comment):

The word domain makes me think of something as Runspace level.

Perhaps scope stack is a better alternative (though, strictly speaking, it can be a tree in that multiple sibling child scopes can exist in a single pipeline).

Version(s) of document impacted

  • Impacts 6.next document
  • Impacts 6 document
  • Impacts 5.1 document
  • Impacts 5.0 document
  • Impacts 4.0 document
  • Impacts 3.0 document
@SeeminglyScience

This comment has been minimized.

Copy link

commented May 10, 2019

Perhaps scope stack is a better alternative (though, strictly speaking, it can be a tree in that multiple sibling child scopes can exist in a single pipeline).

Personally I still like stack. While it's true that multiple scopes can be live there can only be one active scope, that's the scope of the current command processor. (note "live" and "active" are terms I just made up, there isn't really an equivalent engine term afaik)

That said, scope tree works fine too. Though with the above in mind, it does also make me think it's referring to the ExecutionContext (albeit less so)

Ultimately I suggest sticking with the terms used by the engine (e.g. SessionState, SessionStateScope, and ExecutionContext) or at the very least include a link to the real underlying type with every reference. If someone wants to learn more about the internals by looking at the source, and all they know is the term "Scope Stack" then they'll get no where.

@mklement0

This comment has been minimized.

Copy link
Contributor Author

commented May 10, 2019

Thanks, @SeeminglyScience.

Given your explanation, I'm leaning towards stack as well.

As for sticking with the internally used terms:

Creating a disconnect between the terminology used in the documentation and the one in the source code is unfortunate, but unavoidable if the priority is to provide descriptive, non-confusing terms to end users (and the source-code terminology doesn't meet that bar) - and I think it should be the priority.

Most end user will likely never look at the source code and therefore needn't know internally used names.

at the very least include a link to the real underlying type with every reference.

I think it would be sufficient:

  • on the documentation side: to establish this link one in about_Scopes, i.e., where these concepts are introduced: briefly mention the name of the underlying source-code construct, and optionally link to it.

  • on the source-code side: to mention the documentation terms in the comments on the various classes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.