From fa0d7a34e4da5934fa480553439c0db4bd7632d9 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 20 Apr 2016 14:30:54 -0700 Subject: [PATCH 1/3] Move known issues to docs folder So only readme and contributing are top level. --- KNOWNISSUES.md => docs/KNOWNISSUES.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename KNOWNISSUES.md => docs/KNOWNISSUES.md (100%) diff --git a/KNOWNISSUES.md b/docs/KNOWNISSUES.md similarity index 100% rename from KNOWNISSUES.md rename to docs/KNOWNISSUES.md From ea73db0d68ad1faed2e9b547bea5cb7fa38f658c Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 20 Apr 2016 15:21:55 -0700 Subject: [PATCH 2/3] Make Start-PSBootstrap re-install dotnet on Windows It now helpfully deletes the previous `dotnet` directory so that older versions of the CLI don't muck things up. --- PowerShellGitHubDev.psm1 | 1 + 1 file changed, 1 insertion(+) diff --git a/PowerShellGitHubDev.psm1 b/PowerShellGitHubDev.psm1 index efaefad038..1e76fb3f01 100644 --- a/PowerShellGitHubDev.psm1 +++ b/PowerShellGitHubDev.psm1 @@ -374,6 +374,7 @@ function Start-PSBootstrap { sudo installer -pkg dotnet-dev-osx-x64.latest.pkg -target / } elseif ($IsWindows -And -Not $IsCore) { + Remove-Item -ErrorAction SilentlyContinue -Recurse -Force ~\AppData\Local\Microsoft\dotnet Invoke-WebRequest -Uri https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/install.ps1 -OutFile install.ps1 ./install.ps1 From ca1055c83c130652efa1ca967ceab9c51109ce55 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 20 Apr 2016 16:25:58 -0700 Subject: [PATCH 3/3] Add Frequently Asked Questions to documentation Addresses some PowerShell, build, and Git questions. --- README.md | 23 ---------- docs/FAQ.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 23 deletions(-) create mode 100644 docs/FAQ.md diff --git a/README.md b/README.md index 6f099ca5cf..b9a9ccf9ff 100644 --- a/README.md +++ b/README.md @@ -75,26 +75,3 @@ easy, we can just clone recursively. ```sh git clone --recursive https://github.com/PowerShell/PowerShell.git ``` - -You can verify that the submodules were initialized properly with: - -```sh -git submodule status -``` - -If they're initialized, it will look like this: - -``` - f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) - c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) - e6bf85694ae8352d77175c4c7d304946e018808c src/windows-build (monad/cc6afbeb-3/31) -``` - -If they're not, there will be minuses in front (and the folders will -be empty): - -``` --f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) --c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) --e6bf85694ae8352d77175c4c7d304946e018808c src/windows-build (monad/cc6afbeb-3/31) -``` diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000000..bf6ad6150f --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,122 @@ +Where can I learn PowerShell's syntax? +====================================== + +[SS64.com](http://ss64.com/ps/syntax.html) is a good resource. + +What are the best practices and style? +====================================== + +The [PoshCode][] unofficial guide is our reference. + +[PoshCode]: https://github.com/PoshCode/PowerShellPracticeAndStyle + +What are PowerShell's scoping rules? +==================================== + +- Variables are created in your current scope unless explicitly indicated. +- Variables are visible in a child scope unless explicitly indicated. +- Variables created in a child scope are not visible to a parent unless + explicitly indicated. +- Variables may be placed explicitly in a scope. + +Things that create a scope: +--------------------------- + +- [functions](http://ss64.com/ps/syntax-functions.html) +- [call operator](http://ss64.com/ps/call.html) (`& { }`) +- [script invocations](http://ss64.com/ps/syntax-run.html) + +Things that operate in the current scope: +----------------------------------------- + +- [source operator](http://ss64.com/ps/source.html) (`. { }`) +- [statements](http://ss64.com/ps/statements.html) (`if .. else`, `for`, `switch`, etc.) + +Why didn't an error throw an exception? +======================================= + +Error handling in PowerShell is a bit weird, as not all errors result in +catchable exceptions by default. Setting `$ErrorActionPreference = 'Stop'` will +likely do what you want; that is, cause non-terminating errors to instead +terminate. Read [An Introduction To Error Handling in PowerShell][error] for +more information. + +[error]: https://blogs.msdn.microsoft.com/kebab/2013/06/09/an-introduction-to-error-handling-in-powershell/ + +Why did `Start-PSBuild` tell me to update `dotnet`? +=================================================== + +We depend on the latest version of the .NET CLI, as we use the output of `dotnet +--info` to determine the current runtime identifier. Without this information, +our build function can't know where `dotnet` is going to place the build +artifacts. + +You can automatically install this using `Start-PSBootstrap`. + +**However, you must first manually uninstall other versions of the CLI.** + +If you have installed via any of the following means: + +- MSI +- `exe` +- `apt-get` +- `pkg` + +You *must* manually uninstall it. + +Additionally, if you've just unzipped their binary drops (or used their obtain +scripts, which do essentially the same thing), you must manually delete the +folder, as the .NET CLI team re-engineered how their binaries are setup, such +that new packages' binaries get stomped on by old packages' binaries. + +Why is my submodule empty? +========================== + +If a submodule (such as `src/Modules/Pester`) is empty, that means it is +uninitialized. If you've already cloned, you can do this with: + +```sh +git submodule init +git submodule update +``` + +You can verify that the submodules were initialized properly with: + +```sh +git submodule status +``` + +If they're initialized, it will look like this: + +``` + f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) + c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) + e6bf85694ae8352d77175c4c7d304946e018808c src/windows-build (monad/cc6afbeb-3/31) +``` + +If they're not, there will be minuses in front (and the folders will +be empty): + +``` +-f23641488f8d7bf8630ca3496e61562aa3a64009 src/Modules/Pester (f23641488) +-c99458533a9b4c743ed51537e25989ea55944908 src/libpsl-native/test/googletest (release-1.7.0) +-e6bf85694ae8352d77175c4c7d304946e018808c src/windows-build (monad/cc6afbeb-3/31) +``` + +Please note that the commit hashes for the submodules have likely changed since +this FAQ was written. + +Why does my submodule say "HEAD detached at" some commit? +========================================================= + +When a submodule is first initialized and updated, it is not checked out to a +branch, but the very exact commit that the superproject (this PowerShell +repository) has recorded for the submodule. This is the intended behavior. + +If you want to check out an actual branch, just do so with `git checkout +`. A submodule is just a Git repository; it just happens to be nested +inside another repository. + +Please read the Git Book chapter on [submodules][]. + +[submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules