Help System as a standalone PowerShell Module #102

adityapatwardhan · 2017-07-27T18:05:40Z

This RFC proposes making HelpSystem as a standalone PowerShell module and remove it from System.Management.Automation.dll.

This change is

iSazonov · 2017-08-03T09:31:43Z

2-Draft-Accepted/RFCNNN-HelpSystem-As-A-Module.md

+Help system is used predominantly in interactive sessions and hence not required for automation scenarios.
+Since, it is part of System.Management.Automation.dll it is always loaded with PowerShell.
+Help system is sizeable piece of code, which increases the runtime footprint of the process.
+This RFC proposes to make the help system a PowerShell module, so it is loaded only when used.


We could add HelpSystem abstract class to allow customers to implement help system themselves.

I intend to implement a plugin model. Since that is implementation detail, I did not include it in here.

If you have thoughts on public api's, I think it's worth including here or note that it'll be in a separate RFC

It make sense to write this explicitly that users can implement custom Help system module based on new public API..

I will update this to specific the new public APIs.

If the intention is to make a plugin model will this root code in the engine? I would see all help root code in a separate module, and plugins in other modules.

iSazonov · 2017-08-03T09:36:34Z

2-Draft-Accepted/RFCNNN-HelpSystem-As-A-Module.md

+| UpdatableHelpCommandBase | Used by UpdateHelpCommand, breaking change impact is medium.
+| UpdateHelpCommand | Sealed class, breaking change impact is low.
+
+[CLR Type Forwarding](https://docs.microsoft.com/en-us/dotnet/framework/app-domains/type-forwarding-in-the-common-language-runtime) will be considered to lessen the impact of the breaking change.


I think we should state this as main solution.

I will mostly likely be used. I still need to investigate the impact if the forwarded type is not found, for example Microsoft.PowerShell.HelpSystem module is removed.

Actually, this might not be feasible as type forwarding only works if the namespace is same.

We could place mandatory types in mandatory assembly (maybe leave in SMA) and any extentions put in optional assemblies (and maybe another namespace).
HelpSystem is based on help providers so we could consider to make the help providers as optional and loadable.

vors · 2017-08-23T06:02:37Z

This is great, love it

joeyaiello · 2018-04-04T23:01:37Z

@PowerShell/powershell-committee has decided to take this into the experimental folder so that we can begin prototyping/implementing without blocking on a vote.

I personally want to follow up on the CLR type forwarding aspect of this scenario, so @adityapatwardhan and company are going to be doing some investigation there as part of the prototyping effort.

HemantMahawar · 2018-07-25T22:53:07Z

2-Draft-Accepted/RFCNNN-HelpSystem-As-A-Module.md

+
+[CLR Type Forwarding](https://docs.microsoft.com/en-us/dotnet/framework/app-domains/type-forwarding-in-the-common-language-runtime) will be considered to lessen the impact of the breaking change.
+
+The interactive user experience would not change as command discovery will find the ```Get-Help```, ```Save-Help``` and ```Update-Help``` commands from the 'Microsoft.PowerShell.HelpSystem' module instead from 'Microsoft.PowerShell.Core' module (System.Management.Automation.dll).


We need to make sure that scripting scenarios with fully qualified module names (Microsoft.PowerShell.Core\Get-Help) is NOT broken. PowerShell engine should support both - old module qualified names and the new module qualified names.

HemantMahawar · 2018-07-25T22:54:43Z

2-Draft-Accepted/RFCNNN-HelpSystem-As-A-Module.md

+Plan to implement: Yes
+---
+
+# Help System as a standalone PowerShell Module  


We should put this new module behind experimental flag.

SteveL-MSFT · 2019-01-28T20:31:28Z

@adityapatwardhan there's some comments that need to be addressed before @PowerShell/powershell-committee will review

iSazonov · 2019-01-29T11:42:29Z

I tried decouple in https://github.com/iSazonov/PowerShell/tree/helpsystem (not finished, now stopped on res files and HelpV3_format_ps1xml.cs)

there are too many changes to use the experimental flag - we will have to cut off
we need rewrite Help function to cmdlet before the decouple. (It would be nice to do this before 6.2. ) I think we need add this to the RFC for review in PowerShell Committee.

Perhaps it is better to migrate to markdown before the decouple - this will remove many dependencies and make it easier the decouple.

joeyaiello · 2020-02-25T20:21:57Z

@PowerShell/powershell-committee agrees that this might still be relevant for the 7.1 timeframe, but @adityapatwardhan is busy with some stuff and will come back to the RFC at a later date.

iSazonov · 2020-02-26T16:25:43Z

I still believe we could decouple Help System from Engine in the first step. This simplify next steps. While @adityapatwardhan is busy anybody from MSFT team could help me to finish the work. This shouldn't change current behavior and add a breaking change but will add a new temporary public API.

ScriptAutomate · 2020-03-03T02:57:48Z

2-Draft-Accepted/RFCNNN-HelpSystem-As-A-Module.md

+## Updatable help
+
+Updatable help will be updated to directly consume markdown help content.
+It includes adding the markdown help content into the cab / zip files of help content that is downloaded.
+CommandHelpProvider and HelpFileHelpProvider will be updated to consume markdown help content.


This! I'm definitely on board. I think many people get stuck only using comment-based help because of the difficulty in the approach to help documentation. This would probably be able to approach solving issues that continue to pop up like what's seen here: MicrosoftDocs/windows-powershell-docs#139

If the barrier-to-entry for making help documentation was improved like this, it would be a big deal. Without something like platyPS to help, MAML-xml is a rough world to wrap toolchains around. Though, I don't have much experience with platyPS, myself.

joeyaiello · 2020-04-07T19:43:12Z

Just to reiterate, we're still too busy to do this one within the PowerShell Team, and @adityapatwardhan does have a WIP PR, but we do think that it's fine to proceed forward if someone has the right expertise to do it. That being said, they should comment here and make sure to coordinate with @adityapatwardhan to avoid duplicating work.

iSazonov · 2020-04-08T04:12:24Z

@adityapatwardhan does have a WIP PR

Can you point the PR?
I tried decouple (as first step in the direction) the module but was blocked because I believe we need new public API to register external Help module (or use PSReadline way that is perhaps expensive).

joeyaiello · 2020-11-03T20:35:27Z

This RFC is mostly dependent on solving the CLR type forwarding problem and implementing the concept of PowerShell "subsystems" or non-module code. While this is something PS Team would like to do at some point, it's not currently a priority, and we would want to re-visit the thinking completely after those other problems are solved.

We spoke to @adityapatwardhan offline and determined that withdrawing the RFC would be the best path forward (at least for now).

iSazonov · 2020-11-04T05:19:43Z

We spoke to @adityapatwardhan offline and determined that withdrawing the RFC would be the best path forward (at least for now).

I hope MSFT continues public discussion in new RFC since new subsystem concept looks great.
Is it worth it for so long to knock on this door if you never enter it? :-)

Main questions:

Does MSFT team agree to accept this as full breaking change (cut off Help module and replace with new Help subsystem)?
Do we want to have a co-existence and an backward compatibility?
- on API (SDK) level
- on cmdlet level (including parameters)
Should we always (if no Help module or Help subsystem are loaded) have minimal Help function and/or Get-Help cmdlet?

I believe we could start to develop new Help subsystem (as experimental feature) in any time so that overlap current Help module in runtime on the fly.
I am convinced that in any case, we have to decuple Help module from Engine (but leave in the repo as is in the time). I tried to do this and was stopped by a breaking change. I believe we can accept the breaking change and 7.2 (non LTS) milestone is best time for this.
I don't know about minimal Get-Help cmdlet in core but Help function we could implement in way as we do with PSReadline with detection on the fly:

no Help module or Help subsystem loaded
either Help module or Help subsystem loaded
both Help module or Help subsystem loaded

I guess the decoupling (with new Help subsystem stub) could be done by MSFT team in hours. Or I'd do this. At least we could pull a draft and discuss.

With having Help subsystem stub you open a way for community contributions.

It seems @daxian-dbw said that MSFT team would implement a subsystem(s) to get an experience. Why did not start with Help subsystem? This is faster and easier to do, and has less negative impact on compatibility.

joeyaiello · 2021-03-02T20:16:38Z

@iSazonov: these are good questions, but right now we're driving the subsystem work through some internal business needs we have for decoupling DSC and remoting functionality from the PowerShell engine.

Another reason for doing this with something more complicated first, rather than with the help system, is because the help system may drive a more limited design that precludes flexibility and more advanced subsystems in the future.

Given that, we're going to close this RFC to be potentially be reopened in the future when subsystems are further along and we want to revisit the help system.

iSazonov · 2021-03-03T07:13:16Z

@joeyaiello I understand and support your plans.
However, I should note that:

I would rather expect it to be a separate module but not a subsystem
even if it will be a subsystem, we most likely want to be able to disable it and enable the old module for a transitional time

So maybe we should partially separate this module from the engine now. (My PR is still open.)
If not, then I would suggest you make a blog post to announce that this module will be removed in the next few years.

msftclas added the cla-not-required label Jul 27, 2017

iSazonov reviewed Aug 3, 2017

View reviewed changes

SteveL-MSFT mentioned this pull request Sep 5, 2017

HelpSystem should consume markdown natively PowerShell/PowerShell#3954

Open

msftgits removed the cla-not-required label Sep 26, 2017

adityapatwardhan added 5 commits March 9, 2018 14:48

Initial draft

79df14d

Fixed typo

f170208

Added CLR Type Forwarding

420cb63

Move the RFC to 2-Draft-Accepted folder

aa4be93

Address code review feedback

1a682e4

adityapatwardhan force-pushed the HelpSystemModule branch from 7da9286 to 1a682e4 Compare April 2, 2018 18:58

joeyaiello added the Review - Committee label Apr 2, 2018

HemantMahawar reviewed Jul 25, 2018

View reviewed changes

SteveL-MSFT added Review - Waiting on Author and removed Review - Committee labels Jan 28, 2019

iSazonov mentioned this pull request Feb 17, 2019

Odd Behavior with Get-Help PowerShell/PowerShell#8875

Closed

ScriptAutomate reviewed Mar 3, 2020

View reviewed changes

Prepare 'RFC0062 - HelpSystem as a Module' for Withdrawal (#1)

6d9b579

joeyaiello closed this Mar 2, 2021


		[CLR Type Forwarding](https://docs.microsoft.com/en-us/dotnet/framework/app-domains/type-forwarding-in-the-common-language-runtime) will be considered to lessen the impact of the breaking change.

		The interactive user experience would not change as command discovery will find the ```Get-Help```, ```Save-Help``` and ```Update-Help``` commands from the 'Microsoft.PowerShell.HelpSystem' module instead from 'Microsoft.PowerShell.Core' module (System.Management.Automation.dll).

Help System as a standalone PowerShell Module #102

Help System as a standalone PowerShell Module #102

Uh oh!

Conversation

adityapatwardhan commented Jul 27, 2017 • edited by SteveL-MSFT Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

vors commented Aug 23, 2017

Uh oh!

joeyaiello commented Apr 4, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveL-MSFT commented Jan 28, 2019

Uh oh!

iSazonov commented Jan 29, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joeyaiello commented Feb 25, 2020

Uh oh!

iSazonov commented Feb 26, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joeyaiello commented Apr 7, 2020

Uh oh!

iSazonov commented Apr 8, 2020

Uh oh!

joeyaiello commented Nov 3, 2020

Uh oh!

iSazonov commented Nov 4, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joeyaiello commented Mar 2, 2021

Uh oh!

iSazonov commented Mar 3, 2021

Uh oh!

Uh oh!

adityapatwardhan commented Jul 27, 2017 •

edited by SteveL-MSFT

Loading

iSazonov commented Jan 29, 2019 •

edited

Loading

iSazonov commented Nov 4, 2020 •

edited

Loading