Add the breaking changes doc #5620

maertendMSFT · 2017-12-04T19:59:45Z

PR Summary

PR Checklist

Note: Please mark anything not applicable to this PR NA.

PR has a meaningful title
- Use the present tense and imperative mood when describing your changes
Summarized changes
[NA] User facing Documentation needed
- [NA] Issue filed - Issue link:
Change is not breaking
[NA] Make sure you've added a new test if existing tests do not effectively test the code changed
- [NA] Add [feature] if the change is significant or affects feature tests
This PR is ready to merge and is not Work in Progress.
- If the PR is work in progress, please add the prefix WIP: to the beginning of the title and remove the prefix when the PR is ready.

TravisEz13 · 2017-12-07T22:05:53Z

You have spelling issues to fix: https://travis-ci.org/PowerShell/PowerShell/jobs/311493778#L3284

TravisEz13 · 2017-12-07T22:07:28Z

Also markdown issues, If you install markdownlint in vs code it will detect these:
https://ci.appveyor.com/project/PowerShell/powershell/build/v6.1.0-preview.7128#L84

maertendMSFT · 2017-12-08T00:15:00Z

@TravisEz13, thanks for point these out. I am aware of the issues, the doc is not ready to merge. This is a working PR

iSazonov · 2017-12-08T04:28:07Z

I see here a problem - not all PRs with breaking changes was labeled.
Currently I am working on Add-Type cmdlet and discover that it was changed a lot, contains bugs and other issues. The important thing is, if you compare the version, it's a lot different than Windows PowerShell cmdlet, but it's not reflected here.
I believe we have many more cases like this.
In perfect case, we would have to check all the cmdlets and all the parameters.

TravisEz13 · 2017-12-15T01:17:48Z

I updated the description with the current PR template. Please fill it out when the PR is ready to be reviewed.

joeyaiello · 2018-01-02T17:41:14Z

Need to add removal of Pester (#5458) and cmdlet/module availability per https://github.com/PowerShell/PowerShell/blob/2be13a623eae2583604ab51449eefc10a8fd9c12/test/powershell/engine/Basic/DefaultCommands.Tests.ps1

SteveL-MSFT · 2018-01-03T01:18:57Z

docs/BREAKINGCHANGES.md

 ### Change $OutputEncoding to use iso-8859-1 encoding rather than ASCII [5361](https://github.com/PowerShell/PowerShell/issues/5361)
-TODO
-
+This is marked as a breaking change because the output of the pipeline is not altered as it was previously, anyone relying on ascii encoding (especially for extended ascii sequences) will no longer have that behavior.


This description isn't correct. Also, I don't think we need to mention "breaking change" in the description since the doc itself is about breaking changes. The PR linked to is not valid as we closed that one and decided to use UTF-8 instead of ISO-8859-1. Correct PR is #5369. I suggest using:

The default encoding of output was previously ASCII (7-bit) which in some cases resulted in incorrect alteration of the output. Change is to default to UTF-8 NoBOM which preserves unicode output with an encoding supported by most tools and operating systems.

SteveL-MSFT · 2018-01-03T01:20:28Z

docs/BREAKINGCHANGES.md

+When an API returns just `null`, Invoke-RestMethod was serializing this as the string `"null"` instead of `$null`.  This change fixes the logic in `Invoke-RestMethod` to properly serialize a valid single value JSON `null` literal as `$null`.


 ### Remove DCOM support from *-Computer cmdlets (replacement for 5152) [5277](https://github.com/PowerShell/PowerShell/issues/5277)


You need to escape the asterisk otherwise markdown things you're emphasizing everything:

\*-Computer

Applies everywhere below.

SteveL-MSFT · 2018-01-03T01:21:38Z

docs/BREAKINGCHANGES.md


 ### Remove DCOM support from *-Computer cmdlets (replacement for 5152) [5277](https://github.com/PowerShell/PowerShell/issues/5277)
-TODO
+DCOM is not supported in corefx, therefore the *-Computer cmdlets were removed.


The *-Computer cmdlets are still there on Windows (since they rely on WMI), but the -ComputerName parameter was removed since it relied on RPC (DotNet remoting).

SteveL-MSFT · 2018-01-03T01:22:24Z

docs/BREAKINGCHANGES.md

-
-### Fix performance issues in Add-Type [5243](https://github.com/PowerShell/PowerShell/issues/5243)
-TODO
+To speed up spope creation, AllScope was removed from most default aliases.  AllScope was left for a few frequently used aliases where the lookup was faster.


Should we have different sections for impactful Breaking Changes and technical Breaking Changes? This one falls under the latter where it shouldn't affect anyone.

SteveL-MSFT · 2018-01-03T01:23:30Z

docs/BREAKINGCHANGES.md


 ### fix get-item -literalpath a*b if `a*b` doesn't actually exist to return error [5197](https://github.com/PowerShell/PowerShell/issues/5197)
-TODO
+Previously, `-literalpath` given a wildcard will treat it the same as -path and if the wildcard found no files, it would silently exit. Correct behavior should be that -literalpath is literal so if the file doesn't exist, it should error. Fix is to also see if wildcard is being suppressed.


Last sentence should be: Change is to treat wildcards used with -Literal as literal.

Also, use semantic linefeeds.

SteveL-MSFT · 2018-01-03T01:48:51Z

docs/BREAKINGCHANGES.md


-### Rename $IsOSX to $IsMacOS [4757](https://github.com/PowerShell/PowerShell/issues/4757)
-TODO
+### Rename $IsOSX to $IsacOS [4700](https://github.com/PowerShell/PowerShell/issues/4700)


typo $IsMacOS

SteveL-MSFT · 2018-01-03T01:50:07Z

docs/BREAKINGCHANGES.md


 ### Make error message consistent when invalid script is passed to -File, better error when passed ambiguous arg [4573](https://github.com/PowerShell/PowerShell/issues/4573)
-TODO
+TODO (I believe the breaking change here is for "Enable -WindowStyle to work", changing the exit code.  Need to confirm)


No need to mention enabling -WindowStyle to work, the breaking change is modifying exit codes of pwsh.exe to align with Unix conventions.

SteveL-MSFT · 2018-01-03T01:50:47Z

docs/BREAKINGCHANGES.md


 ### Due to the use of unsupported APIs, we must remove the Counter CmdLets in the Diagnostics Module until a better solution is found. [4303](https://github.com/PowerShell/PowerShell/issues/4303)
-TODO
+TODO (Not sure how to document more than the title)


Should be a separate section on cmdlet coverage compared to Windows PowerShell

SteveL-MSFT · 2018-01-03T01:50:56Z

docs/BREAKINGCHANGES.md


 ###  Due to the use of unsupported APIs, we must remove the LocalAccounts module until a better solution is found. [4302](https://github.com/PowerShell/PowerShell/issues/4302)
-TODO
+TODO (Not sure how to document more than the title)


Should be a separate section on cmdlet coverage compared to Windows PowerShell

SteveL-MSFT · 2018-01-03T01:52:09Z

docs/BREAKINGCHANGES.md

 ### Change positional parameter for powershell.exe from -Command to -File [4019](https://github.com/PowerShell/PowerShell/issues/4019)
-TODO
-
+This fixes the usage of `#!` in PowerShell scripts that are being executed from non-PowerShell shells on non-Windows platforms.


Enable shebang use of PowerShell on non-Windows platforms. This means on Unix based systems,
you can make a script executable which would invoke PowerShell automatically rather than explicitly
invoking pwsh.

SteveL-MSFT · 2018-01-03T04:29:56Z

@maertendMSFT looks like you made a big update while I was adding comments so they appear "out dated", but you should look at them to see if they've been addressed since GitHub doesn't know

iSazonov · 2018-01-08T09:10:55Z

docs/BREAKINGCHANGES.md


+### Unify cmdlets with parameter `Encoding` to be of type `System.Text.Encoding` [#5080](https://github.com/PowerShell/PowerShell/issues/5080)

+<<<<<<< HEAD


iSazonov · 2018-01-08T09:11:08Z

docs/BREAKINGCHANGES.md

+The `-Encoding` value `Byte` has been removed from the filesystem provider cmdlets.
+A new parameter `-Byte` is now used to specify that a byte stream is required as input or that output will be a stream of bytes.
+
+>>>>>>> reformatting to BREAKINGCHANGES


iSazonov · 2018-01-08T09:11:18Z

docs/BREAKINGCHANGES.md

 Previously, an enum value of `Byte` was used with `-Encoding` to indicate a byte stream.
 However, `Byte` is not an actual encoding.  The change is remove that enum value and replace
 it with a `-AsByteStream` switch to indicate input or output should be a byte stream.
+=======


SteveL-MSFT · 2018-01-09T18:35:54Z

docs/BREAKINGCHANGES.md

+In order to give users a deterministic way to call PowerShell Core on Windows (as opposed to Windows PowerShell),
+the PowerShell Core binary was changed to `pwsh.exe` on Windows and `pwsh` on non-Windows platforms.
+
+Additionally, this was done to reduce the typing time to open PowerShell,


I don't think this is worth calling out the reduced typing time. Instead you can say: The shortened name is also consistent with naming of shells on non-Windows platforms.

SteveL-MSFT · 2018-01-09T18:36:28Z

docs/BREAKINGCHANGES.md

+Additionally, this was done to reduce the typing time to open PowerShell,
+especially for non-Windows users who are used to three or four letter shell names.
+
+In the future, some kind of alias or symbolic link for `powershell` may be added to non-Windows platforms.


I wouldn't mention this particularly since dotnetcore doesn't work if the symlink doesn't match the library name

SteveL-MSFT · 2018-01-09T18:38:29Z

docs/BREAKINGCHANGES.md

+### Skip null-element check for collections with a value-type element type [#5432](https://github.com/PowerShell/PowerShell/issues/5432)
+For the `Mandatory` parameter and `ValidateNotNull` and `ValidateNotNullOrEmpty` attributes, skip the null-element check if the collection's element type is value type.  
+
+### Change `$OutputEncoding` to use `iso-8859-1` encoding rather than ASCII [#5369](https://github.com/PowerShell/PowerShell/issues/5369)


Should be UTF8 w/o BOM instead of iso-8859-1

SteveL-MSFT · 2018-01-09T18:39:33Z

docs/BREAKINGCHANGES.md

+To speed up scope creation, `AllScope` was removed from most default aliases.
+`AllScope` was left for a few frequently used aliases where the lookup was faster.
+
+### Don't wrap `stderr` as `ErrorRecord` [#5190](https://github.com/PowerShell/PowerShell/issues/5190)


This PR was closed and not merged. Remove.

SteveL-MSFT · 2018-01-09T18:40:16Z

docs/BREAKINGCHANGES.md

+
+### `-Verbose` and `-Debug` no longer overrides `$ErrorActionPreference` [#5113](https://github.com/PowerShell/PowerShell/issues/5113)
+
+Previously, if `-Verbose` or `-Debug` were specified, it overrode the behavior of `$ErrorActionPreference`.


I think it should be was, not were. Sounds better to me, but not an English major.

I think this could go either way, since there are 2 parameters specified I used there plural were. But was would be appropriate because the parameters can be used individually. In this case, I think were is correct since we are listing multiple parameters.

SteveL-MSFT · 2018-01-09T20:32:19Z

docs/BREAKINGCHANGES.md

+However, this change now requires that you explicitly specify `-c` or `-Command` when trying to do things like `powershell.exe Get-Command`.
+
+### Implement Unicode escape parsing [#3958](https://github.com/PowerShell/PowerShell/issues/3958)
+TODO


I think you can just say:

`u#### or `u{####} is converted to the corresponding Unicode character. To output a literal `u, escape the backtick: ``u.

SteveL-MSFT · 2018-01-09T20:33:50Z

docs/BREAKINGCHANGES.md

+
+### Completions for environment variables differ between platforms [#3227](https://github.com/PowerShell/PowerShell/issues/3227)
+The casing of `$PSModulePath` has been corrected to be consistent with Windows PowerShell.
+TODO: not sure if this actually a breaking change.  If the change is to make something consistent with Windows, there would be no difference between 6.0 and 5.1


I think you can remove this, this was only a breaking change between releases of PSCore6

SteveL-MSFT · 2018-01-09T20:36:54Z

docs/BREAKINGCHANGES.md

+
+
+### Add Get-StringHash and Get-FileHash cmdlets [#3024](https://github.com/PowerShell/PowerShell/issues/3024)
+TODO: Labeled with breaking change so the difference between windows and core can be described


The breaking change is that some hash algorithms are not supported by corefx and so no longer available: MACTripleDES, RIPEMD160

SteveL-MSFT · 2018-01-09T20:37:21Z

docs/BREAKINGCHANGES.md

+
+
+### Add support W3C Extended Log File Format in Import-Csv [#2482](https://github.com/PowerShell/PowerShell/issues/2482)
+Previously, the `Iport-Csv` cmdlet cannot be used to directly import the log files in W3C extended log format and additional action would be required.


typo Import-CSV

@SteveL-MSFT Casing issue. Import-Csv.

@alexandair thanks for the correction of the correction :)

SteveL-MSFT · 2018-01-09T20:39:06Z

docs/BREAKINGCHANGES.md

+
+
+### Parameter binding problem with ValueFromRemainingArguments in PS functions [#2035](https://github.com/PowerShell/PowerShell/issues/2035)
+TODO


ValueFromRemainingArguments now returns the values as an array instead of a single value which itself is an array

joeyaiello · 2018-01-10T09:20:09Z

@TravisEz13 these spelling errors in Travis CI don't make any sense, you mind helping out?

markekraus · 2018-01-10T19:04:02Z

The change in Web Cmdlets from WebRequest to HttpClient introduced several breaking changes As well as some breaking changes around the lack of IE interop. I'm not sure if they should be documented here or not, But I feel the need to call them out.

Basic HTML Parsing only (ParsedHtml and Forms properties no longer exist and Invoke-WebRequest now always returns a BasicHtmlWebResponseObject)
BasicHtmlWebResponseObject.Headers values are now String[] instead of String
BasicHtmlWebResponseObject.BaseResponse is now System.Net.Http.HttpResponseMessage (has error handling implications)
Strict RFC header parsing is now defualt for -Headers and -UserAgent (bypass with -SkipHeaderValidation)
file:// and ftp:// URI's are no longer supported.
System.Net.ServicePointManager settings are not honored
No Certificate based authentication on macOS

joeyaiello · 2018-01-10T19:25:20Z

@markekraus thanks for the callout! This is definitely going to be a living document. We're doing the launch in just a few mins...would you mind submitting a PR with that stuff into here? I can't afford to break spelling right now.... :\

TravisEz13 · 2018-01-10T19:26:45Z

One spelling issue, https://travis-ci.org/PowerShell/PowerShell/jobs/327363249#L3337, please fix.

markekraus · 2018-01-10T19:30:34Z

@joeyaiello Might be a few hours, but yes. I will put in a PR for that.. erm.. How do you want it and where?

joeyaiello · 2018-01-10T19:57:50Z

Oh, definitely no rush. It'd be awesome if you just added another H3 summarizing "changes to web cmdlets" or something like. And into this doc in master, please.

You're the best!

Adding the breaking changes doc

167cd1c

maertendMSFT added the Documentation Needed in this repo Documentation is needed in this repo label Dec 4, 2017

maertendMSFT self-assigned this Dec 4, 2017

maertendMSFT requested a review from joeyaiello December 4, 2017 19:59

maertendMSFT removed their assignment Dec 5, 2017

TravisEz13 changed the title ~~Adding the breaking changes doc~~ WIP: Adding the breaking changes doc Dec 8, 2017

TravisEz13 changed the title ~~WIP: Adding the breaking changes doc~~ WIP - Adding the breaking changes doc Dec 8, 2017

Updating with progress

3557a41

updating after first full pass

79548d4

1st pass of formatting on breaking changes

a3d080c

SteveL-MSFT requested changes Jan 3, 2018

View reviewed changes

maertendMSFT and others added 2 commits January 5, 2018 14:22

incorporating Steve's changes

7b5d1c4

reformatting to BREAKINGCHANGES

3d323c0

iSazonov reviewed Jan 8, 2018

View reviewed changes

maertendMSFT and others added 4 commits January 8, 2018 10:25

Removing PRs that were not merged & typos

ce2fca8

more forgotten changes on breakingchanges

b1b22fd

Filled in a few of the remaining TODOs

4b9f29b

adding explicitly removed functionalities

5adbebf

SteveL-MSFT requested changes Jan 9, 2018

View reviewed changes

maertendMSFT added 2 commits January 9, 2018 15:01

Feedback, grammer, and spelling

457508c

Feedback, grammer, and spelling

8235fa8

joeyaiello added 2 commits January 9, 2018 22:58

fix lint/spelling and add desc in BREAKINGCHANGES

f32f591

more spelling fixes for BREAKINGCHANGES

9349b0c

joeyaiello added 2 commits January 10, 2018 10:20

maybe fix the spellcheck on BREAKINGCHANGES?

4c76475

last spell fix for BREAKINGCHANGES

5f974bd

joeyaiello changed the title ~~WIP - Adding the breaking changes doc~~ Adding the breaking changes doc Jan 10, 2018

joeyaiello removed the Documentation Needed in this repo Documentation is needed in this repo label Jan 10, 2018

add psd1 to .spelling

16c6a60

maertendMSFT changed the title ~~Adding the breaking changes doc~~ Add the breaking changes doc Jan 10, 2018

TravisEz13 approved these changes Jan 10, 2018

View reviewed changes

TravisEz13 self-assigned this Jan 10, 2018

SteveL-MSFT approved these changes Jan 10, 2018

View reviewed changes

TravisEz13 merged commit bb6823d into PowerShell:master Jan 10, 2018

markekraus mentioned this pull request Jan 10, 2018

Update BREAKINGCHANGES.md to Include Web Cmdlets Breaking Changes #5852

Merged

5 tasks

		When an API returns just `null`, Invoke-RestMethod was serializing this as the string `"null"` instead of `$null`. This change fixes the logic in `Invoke-RestMethod` to properly serialize a valid single value JSON `null` literal as `$null`.


		### Remove DCOM support from *-Computer cmdlets (replacement for 5152) [5277](https://github.com/PowerShell/PowerShell/issues/5277)


		### Unify cmdlets with parameter `Encoding` to be of type `System.Text.Encoding` [#5080](https://github.com/PowerShell/PowerShell/issues/5080)

		<<<<<<< HEAD


		### `-Verbose` and `-Debug` no longer overrides `$ErrorActionPreference` [#5113](https://github.com/PowerShell/PowerShell/issues/5113)

		Previously, if `-Verbose` or `-Debug` were specified, it overrode the behavior of `$ErrorActionPreference`.



		### Add Get-StringHash and Get-FileHash cmdlets [#3024](https://github.com/PowerShell/PowerShell/issues/3024)
		TODO: Labeled with breaking change so the difference between windows and core can be described



		### Add support W3C Extended Log File Format in Import-Csv [#2482](https://github.com/PowerShell/PowerShell/issues/2482)
		Previously, the `Iport-Csv` cmdlet cannot be used to directly import the log files in W3C extended log format and additional action would be required.



		### Parameter binding problem with ValueFromRemainingArguments in PS functions [#2035](https://github.com/PowerShell/PowerShell/issues/2035)
		TODO

Add the breaking changes doc #5620

Add the breaking changes doc #5620

Uh oh!

Conversation

maertendMSFT commented Dec 4, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

TravisEz13 commented Dec 7, 2017

Uh oh!

TravisEz13 commented Dec 7, 2017

Uh oh!

maertendMSFT commented Dec 8, 2017

Uh oh!

iSazonov commented Dec 8, 2017

Uh oh!

TravisEz13 commented Dec 15, 2017

Uh oh!

joeyaiello commented Jan 2, 2018

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!

SteveL-MSFT commented Jan 3, 2018

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!

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!

joeyaiello commented Jan 10, 2018

Uh oh!

markekraus commented Jan 10, 2018

maertendMSFT commented Dec 4, 2017 •

edited

Loading