Proposed Release Notes for first 4.x RTM Version

[alx9r]

Pursuant to discussion in #811 here is a draft of release notes for whatever the first 4.x RTM version will be ($first4xRTM). These would be the first dedicated release notes for Pester. This will also be the first RTM version that includes the major changes that occurred between versions 3 and 4. Accordingly, the release notes I am proposing should include all the salient user-observable changes between 3.4.6 and $first4xRTM. If I missed anything, please tell me.

I propose that release notes for each version be kept up-to-date on the github releases page.

I also propose that all other mentions of release notes provide only a link to the github releases page. The other places that might mention such release notes include the following:

• PowerShell Gallery
• Get-Module Pester -ListAvailable | % ReleaseNotes

I think this is better for the following reasons:

1. Including content in the release notes fields through channels other than the github releases page seems to mean (a possibly unavoidable) risk of those release notes being stale. I don't think that's a good setup considering that important known issues for a release may be published via the release notes well after the release date.
2. We only have to publish the release notes content in one format. Github uses markdown. Pester module manifests are (probably) just plaintext. Who knows what formatting PowerShell gallery supports.
   Each format has its own set of quirks and the potential to sap precious developer time.
3. The release notes content for all other channels is static. This means that the content for those fields can simply be hard-coded and forgotten about.

Proposed Github Releases Page Content

<content>

There is a guide for migrating from Pester 3 to Pester 4 to help you understand how the changes from Pester 3 to Pester 4 might affect your tests.

What's New since 3.4.6:

• Nested Describe{} and Context{}. Now you can group tests using as many Contexts{} and Describe{} blocks in any order. The use of mocks in Describe{} and Context{} blocks nested deeper than one of each is still unexplored territory, so proceed with an appropriate amount of caution.
• Improved and color-coded summaries output by Invoke-Pester. No more misreading that all your tests are failed!
• Invoke-Pester now includes the name of the script it is currently executing. No more guessing which file a failed test is in!
• Custom Should operators. Use Add-AssertionOperator to write your own assertions. You could write an operator that allows you to write the working assertion $person | Should beAwesome.
• Array assertions. Should now inspects array contents. For example, 1,2,3 | Should be 1,2,4 produces a user-friendly failure message. It even works recursively, so assertions like 1,@(2,3) | Should be 1,@(2,4) work.
• Code coverage output in JaCoCo format. Use Invoke-Pester's -CodeCoverage and -CodeCoverageOutputFile parameters to produce code coverage reports that integrate with many CI tools.
• Support for Gherkin.
• Smaller distribution package. Files not necessary for end-users are now omitted from Pester packages.
• Pester's implementation of mocks changed significantly. That means you might observe some subtle differences in behavior. See the migration guide for more details.

Deprecated starting with 4.0.0:

• The New-TestDriveItem command has been deprecated.
• The -Quiet parameter of the Invoke-Pester command has been deprecated. Use -Show None instead.

Removed starting with 4.0.0:

• The -OutputXml parameter of the Invoke-Pester command was deprecated already, now it has been removed. Use -OutputFormat and -OutputFile instead.

</content>

Proposed Release Notes Content for all Other Places

<content>

Please find the latest release notes for all versions of Pester at https://github.com/pester/Pester/releases

</content>

[nohwnd]

Imho the code coverage output to jacoco is worth mentioning. The packages Pester ships in should also be smaller because all unnecessary files are deleted from them, how much smaller I did not check :) There will very likely be two more breaking changes that are not in the codebase yet: Contains* to FileContentMatch*, and the Progress reporting will get disabled by default as it has big performance overhead. What we will use to to enable it again I am not sure yet. You can find those issues in milestone 4, if you want to discuss those changes. (Sorry for the lack of formatting, I am writing this from a phone :) )

[alx9r]

Imho the code coverage output to jacoco is worth mentioning.

I omitted this by mistake. I have added it.

The packages Pester ships in should also be smaller because all unnecessary files are deleted from them...

Cool. I did not know about this. I have added this.

There will very likely be two more breaking changes that are not in the codebase yet...

I will add those to the proposed release notes once they are completed.

[nohwnd]

I am drafting the release notes in our releases.

• Added the new Should syntax

• Deprecated Should without dashes (without warning message for the moment)

• Changed all assertion examples to use the new form of shoulds with dashes

• Added breaking changes

• The 3.4.6 package is not smaller compared to the 4.0.6 package, but I kept the wording anyway. It is smaller than it would be if all the tests would be kept in 🙂

[alx9r]

@nohwnd I don't see 4.0.7 at that URL.

[it-praktyk]

I can see v. 4.0.7

I don't see - it should probably be in part about a nested Describe{} - information that in that case Tag can be used only once. I remember discussions with @dlwyatt that only "more external tag usage is handled".

[alx9r]

@nohwnd Per github documentation:

...Only users with write access to the repository can view drafts of releases...

I'm pretty sure I don't have write access. I assume @it-praktyk does.

[nohwnd]

@alx9r you are now part of our team :) well deserved. Please still use PR to sending changes, instead of committing directly.

[nohwnd]

@it-praktyk added that to the release notes.

[alx9r]

@nohwnd The release notes look good to me. 👍