From 737058f62e826b2ebc33eec66b4535acdccc69fa Mon Sep 17 00:00:00 2001 From: Travis Plunk Date: Mon, 27 Mar 2017 16:44:28 -0700 Subject: [PATCH] Add markdown lint test (#3420) * Fix markdown syntax and spelling issues * update spelling dictionary --- .markdownlint.json | 21 ++++ .spelling | 98 +++++++++++---- CHANGELOG.md | 102 +++++++-------- README.md | 9 +- build.psm1 | 4 +- docker/README.md | 2 +- docs/community/governance.md | 2 +- docs/installation/linux.md | 14 +-- docs/installation/windows.md | 90 +++++++------ docs/maintainers/issue-management.md | 2 +- docs/testing-guidelines/WritingPesterTests.md | 2 +- .../en-US/PSReadline.md | 4 +- test/common/markdown/gulpfile.js | 55 ++++++++ test/common/markdown/markdown.tests.ps1 | 119 ++++++++++++++++++ test/common/markdown/package.json | 26 ++++ 15 files changed, 414 insertions(+), 136 deletions(-) create mode 100644 .markdownlint.json create mode 100644 test/common/markdown/gulpfile.js create mode 100644 test/common/markdown/markdown.tests.ps1 create mode 100644 test/common/markdown/package.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000000..2223926058 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,21 @@ +{ + "default": true, + "MD004": false, + "MD007": { + "indent": 4 + }, + "MD013": { + "line_length": 240 + }, + "MD026": { + "punctuation": ".,;:!" + }, + "MD029": { + "style": "one" + }, + "MD033": false, + "MD034": false, + "MD038": false, + "MD042": false, + "no-hard-tabs": true +} diff --git a/.spelling b/.spelling index 1c82b2b6aa..7a6b6335ba 100644 --- a/.spelling +++ b/.spelling @@ -21,7 +21,8 @@ env ProgramFiles ssh CentOS -dockerfiles +DockerFile +DockerFiles ResGen catalog cataloged @@ -82,6 +83,23 @@ alpha.8 alpha.9 alpha.15 vscode +AssemblyLoadContext +ConsoleHost +ConvertFrom-Json +crossgen +Get-ChildItem +Get-ComputerInfo +Get-WinEvent +Invoke-RestMethod +Invoke-WebRequest +Microsoft.PowerShell.Archive +PackageManagement +PowerShellGet +PSReadline +Runspace +SecureString +WSMan +xUnit - demos/Azure/README.md AzureRM.NetCore.Preview AzureRM.Profile.NetCore.Preview @@ -97,15 +115,11 @@ New-CronJob - demos/DSC/readme.md - demos/install/README.md download.sh - - demos/powershellget/README.md -PowerShellGet - demos/python/README.md _script.ps1 _script.ps1. - demos/rest/README.md rest.ps1 -Invoke-WebRequest -ConvertFrom-Json - demos/SSHRemoting/README.md PSSessions HostName @@ -147,7 +161,6 @@ Calvo AngelCalvo khansen00 PRs -PSReadline Snover jpsnover Payette @@ -166,7 +179,6 @@ XTerm CmdletProviderClasses CommandDiscovery CommandSearch -ConsoleHost ConsoleHostRunspaceInit ConsoleHostUserInterface ConsoleLineOutput @@ -207,7 +219,6 @@ TypeGen GoogleTest superproject - docs/installation/linux.md -PSReadLine OpenSUSE - docs/installation/windows.md Win8 @@ -244,7 +255,6 @@ launch.json ForEach-Object - docs/maintainers/issue-management.md omi -PackageManagement Microsoft.PowerShell.Core Microsoft.PowerShell.Utility Microsoft.PowerShell.Management @@ -275,7 +285,6 @@ Get-AuthenticodeSignature Set-AuthenticodeSignature Export-BinaryMiLog Import-BinaryMiLog -Get-ChildItem Get-CimAssociatedInstance Get-CimClass Register-CimIndicationEvent @@ -290,7 +299,6 @@ Remove-CimSession New-CimSessionOption Export-Clixml Import-Clixml -Get-ComputerInfo ConvertFrom-Csv ConvertTo-Csv Export-Csv @@ -396,7 +404,6 @@ Enable-PSTrace New-PSTransportOption Disable-PSWSManCombinedTrace Enable-PSWSManCombinedTrace -Invoke-RestMethod Find-RoleCapability Debug-Runspace Get-Runspace @@ -418,7 +425,6 @@ Get-TypeData Remove-TypeData Update-TypeData Get-UICulture -Get-WinEvent New-WinEvent Connect-WSMan Disconnect-WSMan @@ -439,15 +445,12 @@ ConvertTo-Xml Select-xml - docs/testing-guidelines/testing-guidelines.md 100ms -xUnit Api -Runspace MessageAnalyzer TabCompletion Interop DotNet NativeExecution -Microsoft.PowerShell.Archive Microsoft.PowerShell.Core Microsoft.PowerShell.Diagnostics Microsoft.PowerShell.Management @@ -459,7 +462,6 @@ OpenCover corefx DotCover loopback -WSMan Downlevel KPIs PowerBI @@ -474,7 +476,6 @@ New-ApacheVHost FullyQualifiedErrorId FQErrorId TestDrive -Get-Childitem PSDefaultParameterValues-skip nGet-MultiLineString nGet-ContentOut-String @@ -727,16 +728,71 @@ hoc powershell-unix - src/TypeCatalogGen/README.md TypeCatalogGen - - test/csharp/README.md -AssemblyLoadContext - test/README.md csharp fullclr shebang - CHANGELOG.md -v6.0.0 +-Title +alpha.10 +alpha.11 +alpha.12 +alpha.13 +alpha.14 alpha.16 alpha.17 +bool +ContentType +ConvertTo-Html +CoreConsoleHost +crossgen'ing +EXE's +FileCatalog +FilterHashtable +GetParentProcess +hostname +IncludeUserName +InformationRecord +IoT +iSazonov +IsCore +IsCoreCLR +JsonConfigFileAccessor +kittholland +kwiknick +Lee303 +libpsl-native +Microsoft.Management.Infrastructure.Native +Microsoft.PowerShell.LocalAccounts +oneget.org +PetSerAl +powercode +PowerShellProperties +preview1-24530-04 +PSDrive +PseudoParameterBinder +PSReadLine +PVS-Studio +rc2-24027 +rc3-24011 +stdin +StringBuilder +system.manage +TimeZone +TTY's +UserData +v0.1.0 +v0.2.0 +v0.3.0 +v0.4.0 +v0.5.0 +v0.6.0 +v6.0.0 +ValidateNotNullOrEmpty +WebRequest +win7-x86 +WindowsVersion +XPath - test/tools/CodeCoverageAutomation/README.md Start-CodeCoverageRun Coveralls.io. diff --git a/CHANGELOG.md b/CHANGELOG.md index d7da460d0a..56bbc619c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,9 @@ -Changelog -========= +# Changelog + +## v6.0.0-alpha.17 - 2017-03-08 -v6.0.0-alpha.17 - 2017-03-08 ----------------------------- - Update PSRP client libraries for Linux and Mac. - - We now support customer configurations for Office 365 interaction, as well as NTLM authentication for WSMan-based remoting from Linux (more information [here](https://github.com/PowerShell/psl-omi-provider/releases/tag/v1.0.0.18)). (#3271) + - We now support customer configurations for Office 365 interaction, as well as NTLM authentication for WSMan based remoting from Linux (more information [here](https://github.com/PowerShell/psl-omi-provider/releases/tag/v1.0.0.18)). (#3271) - We now support remote step-in debugging for `Invoke-Command -ComputerName`. (#3015) - Use prettier formatter with `ConvertTo-Json` output. (#2787) (Thanks to @kittholland!) - Port `*-CmsMessage` and `Get-PfxCertificate` cmdlets to Powershell Core. (#3224) @@ -16,7 +15,7 @@ v6.0.0-alpha.17 - 2017-03-08 - Remove the `AliasProperty "Count"` defined for `System.Array`. - This removes the extraneous `Count` property on some `ConvertFrom-Json` output. (#3231) (Thanks to @PetSerAl!) - Port `Import-PowerShellDatafile` from PowerShell script to C#. (#2750) (Thanks to @powercode!) -- Add `-CustomMethod` paramter to web cmdlets to allow for non-standard method verbs. (#3142) (Thanks to @Lee303!) +- Add `-CustomMethod` parameter to web cmdlets to allow for non-standard method verbs. (#3142) (Thanks to @Lee303!) - Fix web cmdlets to include the HTTP response in the exception when the response status code is not success. (#3201) - Expose a process' parent process by adding the `CodeProperty "Parent"` to `System.Diagnostics.Process`. (#2850) (Thanks to @powercode!) - Fix crash when converting a recursive array to a bool. (#3208) (Thanks to @PetSerAl!) @@ -25,13 +24,13 @@ v6.0.0-alpha.17 - 2017-03-08 - Allow Windows' reserved device names (e.g. CON, PRN, AUX, etc.) to be used on non-Windows platforms. (#3252) - Remove duplicate type definitions when reusing an `InitialSessionState` object to create another Runspace. (#3141) - Fix `PSModuleInfo.CaptureLocals` to not do `ValidateAttribute` check when capturing existing variables from the caller's scope. (#3149) -- Fix a race bug in WSMan command plugin instance close operation. (#3203) +- Fix a race bug in WSMan command plug-in instance close operation. (#3203) - Fix a problem where newly mounted volumes aren't available to modules that have already been loaded. (#3034) -- Remove year from PowerShell copyright banner at startup. (#3204) (Thanks to @kwiknick!) +- Remove year from PowerShell copyright banner at start-up. (#3204) (Thanks to @kwiknick!) - Fixed spelling for the property name `BiosSerialNumber` for `Get-ComputerInfo`. (#3167) (Thanks to @iSazonov!) -v6.0.0-alpha.16 - 2017-02-15 ----------------------------- +## v6.0.0-alpha.16 - 2017-02-15 + - Add `WindowsUBR` property to `Get-ComputerInfo` result - Cache padding strings to speed up formatting a little - Add alias `Path` to the `-FilePath` parameter of `Out-File` @@ -42,12 +41,12 @@ v6.0.0-alpha.16 - 2017-02-15 - Fix lock contention when compiling the code to run in interpreter - Avoid going through WinRM remoting stack when using `Get-ComputerInfo` locally - Fix native parameter auto-completion for tokens that begin with a single "Dash" -- Fix parser error reporting for incompleted input to allow defining class in interactive host +- Fix parser error reporting for incomplete input to allow defining class in interactive host - Add the `RoleCapabilityFiles` keyword for JEA support on Windows -v6.0.0-alpha.15 - 2017-01-18 ----------------------------- -- Use parens around file length for offline files +## v6.0.0-alpha.15 - 2017-01-18 + +- Use parentheses around file length for offline files - Fix issues with the Windows console mode (terminal emulation) and native executables - Fix error recovery with `using module` - Report `PlatformNotSupported` on IoT for Get/Import/Export-Counter @@ -59,8 +58,8 @@ v6.0.0-alpha.15 - 2017-01-18 - `Invoke-RestMethod` improvements for non-XML non-JSON input - PSRP remoting now works on CentOS without addition setup -v6.0.0-alpha.14 - 2016-12-14 ----------------------------- +## v6.0.0-alpha.14 - 2016-12-14 + - Moved to .NET Core 1.1 - Add Windows performance counter cmdlets to PowerShell Core - Fix try/catch to choose the more specific exception handler @@ -74,8 +73,8 @@ v6.0.0-alpha.14 - 2016-12-14 - Fix `Invoke-WebRequest` with non-text responses on non-Windows platforms - `Write-Progress` performance improvement from `alpha13` reverted because it introduced crash with a race condition -v6.0.0-alpha.13 - 2016-11-22 ----------------------------- +## v6.0.0-alpha.13 - 2016-11-22 + - Fix `NullReferenceException` in binder after turning on constrained language mode - Enable `Invoke-WebRequest` and `Invoke-RestMethod` to not validate the HTTPS certificate of the server if required. - Enable binder debug logging in PowerShell Core @@ -87,7 +86,7 @@ v6.0.0-alpha.13 - 2016-11-22 - Fix background jobs for Unix and Windows - Add `Get-Uptime` to `Microsoft.PowerShell.Utility` - Make `Out-Null` as fast as `> $null` -- Add Dockerfile for windowsservercore and NanoServer +- Add DockerFile for 'Windows Server Core' and 'Nano Server' - Fix WebRequest failure to handle missing ContentType in response header - Make `Write-Host` fast by delay initializing some properties in InformationRecord - Ensure PowerShell Core adds an initial `/` rooted drive on Unix platforms @@ -100,10 +99,10 @@ v6.0.0-alpha.13 - 2016-11-22 - Update build scripts to support win7-x86 runtime - Move PackageManagement code/test to oneget.org -v6.0.0-alpha.12 - 2016-11-03 ----------------------------- +## v6.0.0-alpha.12 - 2016-11-03 + - Fix `Get-ChildItem -Recurse -ErrorAction Ignore` to ignore additional errors -- Don't block pipeline when running Windows exes +- Don't block pipeline when running Windows EXE's - Fix for PowerShell SSH remoting with recent Win32-OpenSSH change. - `Select-Object` with `-ExcludeProperty` now implies `-Property *` if -Property is not specified. - Adding ValidateNotNullOrEmpty to `-Name` parameter of `Get-Alias` @@ -119,8 +118,8 @@ v6.0.0-alpha.12 - 2016-11-03 - Exclude Registry and Certificate providers from UNIX PS - Update PowerShell Core to consume .Net Core preview1-24530-04 -v6.0.0-alpha.11 - 2016-10-17 ----------------------------- +## v6.0.0-alpha.11 - 2016-10-17 + - Add '-Title' to 'Get-Credential' and unify the prompt experience - Update dependency list for PowerShell Core on Linux and OS X - Fix 'powershell -Command -' to not hang and to not ignore the last command @@ -129,16 +128,16 @@ v6.0.0-alpha.11 - 2016-10-17 - Remove most Maximum* capacity variables - Fix 'Get-ChildItem -Hidden' to work on system hidden files on Windows - Fix 'JsonConfigFileAccessor' to handle corrupted 'PowerShellProperties.json' -and defer creating the user setting directory until a write request comes -- Fix variable assignment to not overwrite readonly variables + and defer creating the user setting directory until a write request comes +- Fix variable assignment to not overwrite read-only variables - Fix 'Get-WinEvent -FilterHashtable' to work with named fields in UserData of event logs - Fix 'Get-Help -Online' in PowerShell Core on Windows - Spelling/grammar fixes -v6.0.0-alpha.10 - 2016-09-15 ----------------------------- +## v6.0.0-alpha.10 - 2016-09-15 + - Fix passing escaped double quoted spaces to native executables -- Add Dockerfiles to build each Linux distribution +- Add DockerFiles to build each Linux distribution - `~/.config/PowerShell` capitalization bug fixed - Fix crash on Windows 7 - Fix remote debugging on Windows client @@ -147,23 +146,21 @@ v6.0.0-alpha.10 - 2016-09-15 - Fix `Install-Module` version comparison bug - Spelling fixes -v6.0.0-alpha.9 - 2016-08-15 ---------------------------- +## v6.0.0-alpha.9 - 2016-08-15 - Better man page - Added third-party and proprietary licenses - Added license to MSI -v6.0.0-alpha.8 - 2016-08-11 ---------------------------- +## v6.0.0-alpha.8 - 2016-08-11 -- PowerShell packages pre-compiled with CrossGen +- PowerShell packages pre-compiled with crossgen - `Get-Help` content added - `Get-Help` null reference exception fixed - Ubuntu 16.04 support added - Unsupported cmdlets removed from Unix modules -- PSReadLine long prompt bug fixed -- PSReadLine custom key binding bug on Linux fixed +- PSReadline long prompt bug fixed +- PSReadline custom key binding bug on Linux fixed - Default terminal colors now respected - Semantic Version support added - `$env:` fixed for case-sensitive variables @@ -178,13 +175,12 @@ v6.0.0-alpha.8 - 2016-08-11 - Desired State Configuration MOF compilation ported to Linux - Windows 2012 R2 / Windows 8.1 remoting enabled -v6.0.0-alpha.7 - 2016-07-26 ---------------------------- +## v6.0.0-alpha.7 - 2016-07-26 - Invoke-WebRequest and Invoke-RestMethod ported to PowerShell Core -- Set PSReadLine default edit mode to Emacs on Linux +- Set PSReadline default edit mode to Emacs on Linux - IsCore variable renamed to IsCoreCLR -- LocalAccounts and other Windows-only assemblies excluded on Linux +- Microsoft.PowerShell.LocalAccounts and other Windows-only assemblies excluded on Linux - PowerShellGet fully ported to Linux - PackageManagement NuGet provider ported - Write-Progress ported to Linux @@ -197,8 +193,7 @@ v6.0.0-alpha.7 - 2016-07-26 - FileCatalog cmdlets added back for Windows - Get-ComputerInfo cmdlet added back for Windows -v0.6.0 - 2016-07-08 -------------------- +## v0.6.0 - 2016-07-08 - Targets .NET Core 1.0 release - PowerShellGet enabled @@ -208,12 +203,11 @@ v0.6.0 - 2016-07-08 - Invoke-Item enabled for Linux and OS X - Windows ConsoleHost reverted to native interfaces - Portable ConsoleHost redirection issues fixed -- Bugs with pseudo (and no) TTYs fixed +- Bugs with pseudo (and no) TTY's fixed - Source Depot synced to baseline changeset 717473 - SecureString stub replaced with .NET Core package -v0.5.0 - 2016-06-16 -------------------- +## v0.5.0 - 2016-06-16 - Paths given to cmdlets are now slash-agnostic (both / and \ work as directory separator) - Lack of cmdlet support for paths with literal \ is a known issue @@ -234,10 +228,9 @@ v0.5.0 - 2016-06-16 - Linux xUnit tests are running again - Many more Pester tests are running -v0.4.0 - 2016-05-17 -------------------- +## v0.4.0 - 2016-05-17 -- PSReadLine is ported and included by default +- PSReadline is ported and included by default - Original Windows ConsoleHost is ported and replaced CoreConsoleHost - .NET Core packages set to the RC2 release at build 24103 - OS X 10.11 added to Continuous Integration matrix @@ -246,8 +239,7 @@ v0.4.0 - 2016-05-17 - Microsoft.Management.Infrastructure.Native replaced with package - Many more Pester tests -v0.3.0 - 2016-04-11 -------------------- +## v0.3.0 - 2016-04-11 - Supports Windows, Nano, OS X, Ubuntu 14.04, and CentOS 7.1 - .NET Core packages are build rc3-24011 @@ -261,7 +253,7 @@ v0.3.0 - 2016-04-11 - Host's shell ID changed to `Microsoft.PowerShellCore` - Modules that use C# assemblies can be loaded - `New-Item -ItemType SymbolicLink` supports arbitrary targets -- Readline implementation supports multi-line input +- PSReadline implementation supports multi-line input - `Ctrl-R` provides incremental reverse history search - `$Host.UI.RawUI` now supported - `Ctrl-K` and `Ctrl-Y` for kill and yank implemented @@ -269,19 +261,17 @@ v0.3.0 - 2016-04-11 - Documentation was completely overhauled - Many more Pester and xUnit tests added -v0.2.0 - 2016-03-08 -------------------- +## v0.2.0 - 2016-03-08 - Supports Windows, OS X, Ubuntu 14.04, and CentOS 7.1 - .NET Core packages are build 23907 -- `System.Console` readline is fully functional +- `System.Console` PSReadline is fully functional - Tests pass on OS X - `Microsoft.PowerShell.Platform` module is available - `New-Item` supports symbolic and hard links - `Add-Type` now works - PowerShell code merged with upstream `rs1_srv_ps` -v0.1.0 - 2016-02-23 -------------------- +## v0.1.0 - 2016-02-23 - Supports Windows, OS X, and Ubuntu 14.04 diff --git a/README.md b/README.md index 1dc9f2bde9..809b96e6f7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # ![logo][] PowerShell Welcome to the PowerShell GitHub Community! -PowerShell is a cross-platform (Windows, Linux, and macOS) automation and configuration tool/framework that works well with your existing tools and is optimized for dealing with structured data (e.g. JSON, CSV, XML, etc.), REST APIs, and object models. -It includes a command-line shell, an associated scripting language and a framework for processing cmdlets. - +PowerShell is a cross-platform (Windows, Linux, and macOS) automation and configuration tool/framework +that works well with your existing tools and is optimized for dealing with structured data +(e.g. JSON, CSV, XML, etc.), REST APIs, and object models. It includes a command-line shell, an +associated scripting language and a framework for processing cmdlets. [logo]: assets/Powershell_64.png @@ -149,7 +150,7 @@ PowerShell is licensed under the [MIT license][]. ## Governance -Governance policy for PowerShell project is described [here][]. +Governance policy for PowerShell project is described [here][]. [here]: https://github.com/PowerShell/PowerShell/blob/master/docs/community/governance.md diff --git a/build.psm1 b/build.psm1 index a0f7fbccb0..35b2d61098 100644 --- a/build.psm1 +++ b/build.psm1 @@ -719,7 +719,7 @@ function Start-PSPester { [string]$OutputFile = "pester-tests.xml", [string[]]$ExcludeTag = 'Slow', [string[]]$Tag = "CI", - [string]$Path = "$PSScriptRoot/test/powershell", + [string[]]$Path = @("$PSScriptRoot/test/common","$PSScriptRoot/test/powershell"), [switch]$ThrowOnFailure, [switch]$FullCLR, [string]$binDir = (Split-Path (New-PSOptions -FullCLR:$FullCLR).Output), @@ -805,7 +805,7 @@ function Start-PSPester { $Command += "-PassThru " } - $Command += "'" + $Path + "'" + $Command += "'" + ($Path -join "','") + "'" if ($Unelevate) { $Command += " *> $outputBufferFilePath; '__UNELEVATED_TESTS_THE_END__' >> $outputBufferFilePath" diff --git a/docker/README.md b/docker/README.md index 36307b2fa6..e7486f01f6 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,7 +1,7 @@ Docker ====== -These Dockerfiles enable building and running PowerShell in a container for each Linux distribution we support. +These DockerFiles enable building and running PowerShell in a container for each Linux distribution we support. There are two sets: release and nightly. This requires an up-to-date version of Docker, such as 1.12. diff --git a/docs/community/governance.md b/docs/community/governance.md index 946664e637..9efd8dbef9 100644 --- a/docs/community/governance.md +++ b/docs/community/governance.md @@ -39,7 +39,7 @@ The following types of decisions require a written RFC and ample time for the co * new features or capabilities in PowerShell (e.g. PowerShell classes, PSRP over SSH, etc.) * anything that might require a breaking changes as defined in our [Breaking Changes Contract][breaking-changes] -* new modules, cmdlets, or parameters that ship in the core PowerShell modules (e.g. `Microsoft.PowerShell.*`, `PackageManagement`, `PSReadline`) +* new modules, cmdlets, or parameters that ship in the core PowerShell modules (e.g. `Microsoft.PowerShell.*`, `PackageManagement`, `PSReadLine`) * the addition of new PowerShell Committee Members or Repository Maintainers * any changes to the process of maintaining the PowerShell repository (including the responsibilities of Committee Members, Repository Maintainers, and Area Experts) diff --git a/docs/installation/linux.md b/docs/installation/linux.md index a7e350c163..d5ac1de000 100644 --- a/docs/installation/linux.md +++ b/docs/installation/linux.md @@ -25,7 +25,7 @@ Once the package is installed, run `powershell` from a terminal. ## Ubuntu 14.04 -### Installation via Package Repository +### Installation via Package Repository - Ubuntu 14.04 PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). This is the preferred method. @@ -77,7 +77,7 @@ sudo apt-get remove powershell ## Ubuntu 16.04 -### Installation via Package Repository +### Installation via Package Repository - Ubuntu 16.04 PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). This is the preferred method. @@ -102,7 +102,7 @@ powershell After registering the Microsoft repository once as superuser, from then on, you just need to use `sudo apt-get upgrade powershell` to update it. -### Installation via Direct Download +### Installation via Direct Download - Ubuntu 16.04 Using [Ubuntu 16.04][], download the Debian package `powershell_6.0.0-alpha.17-1ubuntu1.16.04.1_amd64.deb` @@ -133,7 +133,7 @@ This works for Debian Stretch (now testing) as well. > This package also works on Oracle Linux 7 and Red Hat Enterprise Linux (RHEL) 7. -### Installation via Package Repository (preferred) +### Installation via Package Repository (preferred) - CentOS 7 PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). @@ -151,7 +151,7 @@ powershell After registering the Microsoft repository once as superuser, you just need to use `sudo yum update powershell` to update PowerShell. -### Installation via Direct Download +### Installation via Direct Download - CentOS 7 Using [CentOS 7][], download the RPM package `powershell-6.0.0_alpha.17-1.el7.centos.x86_64.rpm` @@ -279,7 +279,6 @@ The PowerShell macOS package come with the necessary libraries patched, and the build script patches the libraries on-the-fly when building from source. You *can* run this command manually if you're having trouble with .NET Core's cryptography libraries. - [openssl]: https://github.com/Homebrew/homebrew-core/blob/master/Formula/openssl.rb [brew]: http://brew.sh/ [homebrew-patch]: https://github.com/Homebrew/brew/pull/597 @@ -292,14 +291,13 @@ You *can* run this command manually if you're having trouble with .NET Core's cr * User modules will be read from `~/.local/share/powershell/Modules` * Shared modules will be read from `/usr/local/share/powershell/Modules` * Default modules will be read from `$PSHOME/Modules` -* PSReadLine history will be recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` +* PSReadline history will be recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` The profiles respect PowerShell's per-host configuration, so the default host-specific profiles exists at `Microsoft.PowerShell_profile.ps1` in the same locations. On Linux and macOS, the [XDG Base Directory Specification][xdg-bds] is respected. - Note that because macOS is a derivation of BSD, instead of `/opt`, the prefix used is `/usr/local`. Thus, `$PSHOME` is `/usr/local/microsoft/powershell/6.0.0-alpha.17/`, diff --git a/docs/installation/windows.md b/docs/installation/windows.md index 6a9f469b4d..942976f08d 100644 --- a/docs/installation/windows.md +++ b/docs/installation/windows.md @@ -1,112 +1,125 @@ -Package Installation Instructions -================================= +# Package Installation Instructions -# MSI: -To install PowerShell on Windows Full SKU (works on Win8 and above - x64 based systems), download either the MSI from [AppVeyor][] for a nightly build, +## MSI + +To install PowerShell on Windows Full SKU (works on Win8 and above - x64 based systems), download either the MSI from [AppVeyor][] for a nightly build, or a released package from our GitHub [releases][] page. The MSI file looks like this - `PowerShell_6.0.0.buildversion.msi` Once downloaded, double-click the installer and follow the prompts. There is a shortcut placed in the Start Menu upon installation. -> By default the package is installed to `$env:ProgramFiles\PowerShell\` -> -> You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\powershell.exe` +* By default the package is installed to `$env:ProgramFiles\PowerShell\` +* You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\powershell.exe` +* Note: On Windows 8.1 / Windows 2012R2, ensure Visual C++ Redistributable + for VS2015 is installed from [here](http://download.microsoft.com/download/9/3/F/93FCF1E7-E6A4-478B-96E7-D4B285925B00/vc_redist.x64.exe). -> Note: On Windows 8.1 / Windows 2012R2, ensure Visual C++ Redistributable -> for VS2015 is installed from [here](http://download.microsoft.com/download/9/3/F/93FCF1E7-E6A4-478B-96E7-D4B285925B00/vc_redist.x64.exe): - -# Deploying on Nano Server +## Deploying on Nano Server These instructions assume that Windows PowerShell is running on the Nano Server image and that it has been generated by the [Nano Server Image Builder](https://technet.microsoft.com/en-us/windows-server-docs/get-started/deploy-nano-server). Nano Server is a "headless" OS and deployment of PowerShell Core binaries can happen in two different ways: 1. Offline - Mount the Nano Server VHD and unzip the contents of the zip file to your chosen location within the mounted image. -2. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location. +1. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location. In both cases, you will need the Windows 10 x64 Zip release package and will need to run the commands within an "Administrator" PowerShell instance. -## Offline Deployment of PowerShell Core +### Offline Deployment of PowerShell Core 1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image. -2. Unmount the image and boot it. -3. Connect to the inbox instance of Windows PowerShell. -4. Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). +1. Unmount the image and boot it. +1. Connect to the inbox instance of Windows PowerShell. +1. Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). -## Online Deployment of PowerShell Core +### Online Deployment of PowerShell Core The following steps will guide you through the deployment of PowerShell Core to a running instance of Nano Server and the configuration of its remote endpoint. * Connect to the inbox instance of Windows PowerShell + ```powershell $session = New-PSSession -ComputerName -Credential ``` + * Copy the file to the Nano Server instance + ```powershell Copy-Item \powershell--win10-win2016-x64.zip c:\ -ToSession $session ``` + * Enter the session + ```powershell Enter-PSSession $session ``` + * Extract the Zip file + ```powershell # Insert the appropriate version. Expand-Archive -Path C:\powershell--win10-win2016-x64.zip -DestinationPath "C:\PowerShellCore_" ``` -* Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). -# Instructions to Create a Remoting Endpoint +* Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). -Beginning with 6.0.0-alpha.9, the PowerShell package for Windows includes a WinRM plug-in (pwrshplugin.dll) and an installation script (Install-PowerShellRemoting.ps1). -These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified. +## Instructions to Create a Remoting Endpoint -## Motivation +Beginning with 6.0.0-alpha.9, the PowerShell package for Windows includes a WinRM plug-in (pwrshplugin.dll) and an installation script (Install-PowerShellRemoting.ps1). +These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified. -An installation of PowerShell can establish PowerShell sessions to remote computers using `New-PSSession` and `Enter-PSSession`. -To enable it to accept incoming PowerShell remote connections, the user must create a WinRM remoting endpoint. -This is an explicit opt-in scenario where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint. -The installation script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to perform the same action. +### Motivation + +An installation of PowerShell can establish PowerShell sessions to remote computers using `New-PSSession` and `Enter-PSSession`. +To enable it to accept incoming PowerShell remote connections, the user must create a WinRM remoting endpoint. +This is an explicit opt-in scenario where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint. +The installation script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to perform the same action. For more details, please see issue [#1193](https://github.com/PowerShell/PowerShell/issues/1193). -## Script Actions +### Script Actions The script 1. Creates a directory for the plug-in within %windir%\System32\PowerShell -2. Copies pwrshplugin.dll to that location -3. Generates a configuration file -4. Registers that plug-in with WinRM +1. Copies pwrshplugin.dll to that location +1. Generates a configuration file +1. Registers that plug-in with WinRM -## Registration +### Registration The script must be executed within an Administrator-level PowerShell session and runs in two modes. -### Executed by the instance of PowerShell that it will register +#### Executed by the instance of PowerShell that it will register + ``` powershell Install-PowerShellRemoting.ps1 ``` -### Executed by another instance of PowerShell on behalf of the instance that it will register + +#### Executed by another instance of PowerShell on behalf of the instance that it will register + ``` powershell \Install-PowerShellRemoting.ps1 -PowerShellHome "" -PowerShellVersion "" ``` + For Example: + ``` powershell -C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" +C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" ``` + **NOTE:** The remoting registration script will restart WinRM, so all existing PSRP sessions will terminate immediately after the script is run. If run during a remote session, this will terminate the connection. ## How to Connect to the New Endpoint Create a PowerShell session to the new PowerShell endpoint by specifying `-ConfigurationName "some endpoint name"`. To connect to the PowerShell instance from the example above, use either: + ``` powershell New-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" Enter-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" -``` +``` + Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell`. -Artifact Installation Instructions -================================== +## Artifact Installation Instructions We publish an archive with CoreCLR and FullCLR bits on every CI build with [AppVeyor][]. @@ -114,8 +127,7 @@ We publish an archive with CoreCLR and FullCLR bits on every CI build with [AppV [signing]: ../../tools/Sign-Package.ps1 [AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell -CoreCLR Artifacts -================= +## CoreCLR Artifacts * Download zip package from **artifacts** tab of the particular build. * Unblock zip file: right-click in File Explorer -> Properties -> diff --git a/docs/maintainers/issue-management.md b/docs/maintainers/issue-management.md index 24b7fa616b..d57bb8aec6 100644 --- a/docs/maintainers/issue-management.md +++ b/docs/maintainers/issue-management.md @@ -51,7 +51,7 @@ These labels describe what feature area of PowerShell that an issue affects: * `Area-Portability`: anything affecting script portability * `Area-PowerShellGet`: PowerShellGet related issues * `Area-Providers`: PowerShell providers like FileSystem, Certificates, Registry, etc... -* `Area-PSReadline`: PSReadLine related issues +* `Area-PSReadline`: PSReadline related issues * `Area-Remoting`: PSRP issues with any transport layer * `Area-Security`: security related areas like [JEA](https://github.com/powershell/JEA) * `Area-SideBySide`: side by side support diff --git a/docs/testing-guidelines/WritingPesterTests.md b/docs/testing-guidelines/WritingPesterTests.md index 8fd6e27005..1f8c6c8920 100755 --- a/docs/testing-guidelines/WritingPesterTests.md +++ b/docs/testing-guidelines/WritingPesterTests.md @@ -357,4 +357,4 @@ Pester Do and Don't 1. The first `Should` failure will stop that block 2. Don't use `Should` outside of an `It` Block 3. Don't use the word "Error" or "Fail" to test a positive case - 1. ex: "Get-Childitem TESTDRIVE: shouldn't fail", rather "Get-ChildItem should be able to retrieve file listing from TESTDRIVE" + 1. ex: "Get-ChildItem TESTDRIVE: shouldn't fail", rather "Get-ChildItem should be able to retrieve file listing from TESTDRIVE" diff --git a/src/Microsoft.PowerShell.PSReadLine/en-US/PSReadline.md b/src/Microsoft.PowerShell.PSReadLine/en-US/PSReadline.md index a99aebe757..c92c487264 100644 --- a/src/Microsoft.PowerShell.PSReadLine/en-US/PSReadline.md +++ b/src/Microsoft.PowerShell.PSReadLine/en-US/PSReadline.md @@ -394,7 +394,7 @@ When BellStyle is set to Audible, specifies the duration of the beep. [Parameter(ParameterSetName = 'Set 1')] ``` -Specifies how PSReadLine should respond to various error and ambiguous conditions. +Specifies how PSReadline should respond to various error and ambiguous conditions. Valid values are: @@ -439,7 +439,7 @@ Specifies the searching history is case sensitive in functions like ReverseSearc [Parameter(ParameterSetName = 'Set 1')] ``` -Specifies how PSReadLine should save history. +Specifies how PSReadline should save history. Valid values are: diff --git a/test/common/markdown/gulpfile.js b/test/common/markdown/gulpfile.js new file mode 100644 index 0000000000..4da3762d06 --- /dev/null +++ b/test/common/markdown/gulpfile.js @@ -0,0 +1,55 @@ +var gulp = require("gulp"); +var concat = require("gulp-concat"); +var through2 = require("through2"); +var markdownlint = require("markdownlint"); + +gulp.task("test-mdsyntax", function task() { + var paths = []; + var rootpath; + + // assign --repoRoot into rootpath + var j = process.argv.indexOf("--rootpath"); + if (j > -1) { + rootpath = process.argv[j + 1]; + } + + if(rootpath == null) + { + throw "--rootpath must be specified before all other parameters" + } + + // parse --filter into paths. --rootpath must be specified first. + var j = process.argv.indexOf("--filter"); + if (j > -1) { + var filters = process.argv[j + 1].split(","); + filters.forEach(function (filter) { + paths.push(rootpath + "/" + filter); + }, this); + } + + if(paths.length == 0) + { + throw "--filter must be specified" + } + + var rootJsonFile = rootpath + "/.markdownlint.json" + var fs = require('fs'); + fs.appendFileSync('markdownissues.txt', '--EMPTY--\r\n'); + gulp.src(paths, { "read": false }) + .pipe(through2.obj(function obj(file, enc, next) { + markdownlint( + { + "files": [file.path], + "config": require(rootJsonFile) + }, + function callback(err, result) { + var resultString = (result || "").toString(); + if (resultString) { + file.contents = new Buffer(resultString); + } + next(err, file); + }); + })) + .pipe(concat("markdownissues.txt", { newLine: "\r\n" })) + .pipe(gulp.dest(".")); +}); diff --git a/test/common/markdown/markdown.tests.ps1 b/test/common/markdown/markdown.tests.ps1 new file mode 100644 index 0000000000..02aca5abce --- /dev/null +++ b/test/common/markdown/markdown.tests.ps1 @@ -0,0 +1,119 @@ +$moduleRootFilePath = Split-Path -Path $PSScriptRoot -Parent + +# Identify the repository root path of the resource module +$repoRootPath = (Resolve-Path -LiteralPath (Join-path $moduleRootFilePath "../..")).ProviderPath +$repoRootPathFound = $false + +Describe 'Common Tests - Validate Markdown Files' -Tag 'CI' { + BeforeAll { + # Skip if not windows, We don't need these tests to run on linux (the tests run fine in travis-ci) + $skip = !$IsWindows + if ( !$skip ) + { + $NpmInstalled = "not installed" + if (Get-Command -Name 'npm' -ErrorAction SilentlyContinue) + { + $NpmInstalled = "Installed" + Write-Verbose -Message "NPM is checking Gulp is installed. This may take a few moments." -Verbose + Start-Process ` + -FilePath "npm" ` + -ArgumentList @('install','--silent') ` + -Wait ` + -WorkingDirectory $PSScriptRoot ` + -NoNewWindow + Start-Process ` + -FilePath "npm" ` + -ArgumentList @('install','-g','gulp','--silent') ` + -Wait ` + -WorkingDirectory $PSScriptRoot ` + -NoNewWindow + } + elseif( -not $env:AppVeyor) + { + <# + On Windows, but not an AppVeyor and pre-requisites are missing + For now we will skip, and write a warning. Work to resolve this is tracked in: + https://github.com/PowerShell/PowerShell/issues/3429 + #> + Write-Warning "Node and npm are required to run this test" + $skip = $true + } + } + } + + AfterAll { + if ( !$skip ) + { + <# + NPM install all the tools needed to run this test in the test folder. + We will now clean these up. + We're using this tool to delete the node_modules folder because it gets too long + for PowerShell to remove. + #> + Start-Process ` + -FilePath "npm" ` + -ArgumentList @('install','rimraf','-g','--silent') ` + -Wait ` + -WorkingDirectory $PSScriptRoot ` + -NoNewWindow + Start-Process ` + -FilePath "rimraf" ` + -ArgumentList @(Join-Path -Path $PSScriptRoot -ChildPath 'node_modules') ` + -Wait ` + -WorkingDirectory $PSScriptRoot ` + -NoNewWindow + } + } + + It "Should not have errors in any markdown files" -Skip:$skip { + $NpmInstalled | should BeExactly "Installed" + $mdErrors = 0 + Push-Location -Path $PSScriptRoot + try + { + $docsToTest = @( + './*.md' + './docs/installation/*.md' + ) + $filter = ($docsToTest -join ',') + &"gulp" test-mdsyntax --silent ` + --rootpath $repoRootPath ` + --filter $filter + + } + catch + { + Write-Warning -Message ("Unable to run gulp to test markdown files. Please " + ` + "be sure that you have installed nodejs and have " + ` + "run 'npm install -g gulp' in order to have this " + ` + "text execute.") + } + finally + { + Pop-Location + } + + $LASTEXITCODE | Should beexactly 0 + + $mdIssuesPath = Join-Path -Path $PSScriptRoot -ChildPath "markdownissues.txt" + + $mdIssuesPath | should exist + + Get-Content -Path $mdIssuesPath | ForEach-Object -Process { + if ([string]::IsNullOrEmpty($_) -eq $false -and $_ -ne '--EMPTY--') + { + Write-Warning -Message $_ + $mdErrors ++ + } + } + + Remove-Item -Path $mdIssuesPath -Force -ErrorAction SilentlyContinue + + if($mdErrors -gt 0) + { + Write-Warning 'See https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md for an explination of the error codes.' + } + + $mdErrors | Should Be 0 + } +} diff --git a/test/common/markdown/package.json b/test/common/markdown/package.json new file mode 100644 index 0000000000..f1b4661e62 --- /dev/null +++ b/test/common/markdown/package.json @@ -0,0 +1,26 @@ +{ + "name": "powershell.common.markdown.tests", + "version": "1.0.0", + "description": "The PowerShell Common MarkDown Tests.", + "main": "gulpfile.js", + "dependencies": { + "gulp": "^3.9.1", + "through2": "^2.0.1", + "markdownlint": "^0.2.0" + }, + "devDependencies": { + "gulp-concat": "^2.6.1", + "gulp-debug": "^3.0.0", + "markdownlint": "^0.4.0" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/PowerShell/PowerShell.git" + }, + "author": "Microsoft Corporation", + "license": "MIT", + "bugs": { + "url": "https://github.com/PowerShell/PowerShell/issues" + }, + "homepage": "https://github.com/PowerShell/PowerShell#readme" +}