From 9ffebab8038a727dbc97c075ccce71f68fd92514 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:42:57 -0700 Subject: [PATCH 1/9] Fix learning-powershell path There was a random capital S. --- .../debugging-from-commandline.md | 0 .../learning-powershell.md | 0 .../powershell-beginners-guide.md | 0 .../using-ise.md | 0 .../using-vscode.md | 0 .../vscode.png | Bin 6 files changed, 0 insertions(+), 0 deletions(-) rename docs/{learning-powerShell => learning-powershell}/debugging-from-commandline.md (100%) rename docs/{learning-powerShell => learning-powershell}/learning-powershell.md (100%) rename docs/{learning-powerShell => learning-powershell}/powershell-beginners-guide.md (100%) rename docs/{learning-powerShell => learning-powershell}/using-ise.md (100%) rename docs/{learning-powerShell => learning-powershell}/using-vscode.md (100%) rename docs/{learning-powerShell => learning-powershell}/vscode.png (100%) diff --git a/docs/learning-powerShell/debugging-from-commandline.md b/docs/learning-powershell/debugging-from-commandline.md similarity index 100% rename from docs/learning-powerShell/debugging-from-commandline.md rename to docs/learning-powershell/debugging-from-commandline.md diff --git a/docs/learning-powerShell/learning-powershell.md b/docs/learning-powershell/learning-powershell.md similarity index 100% rename from docs/learning-powerShell/learning-powershell.md rename to docs/learning-powershell/learning-powershell.md diff --git a/docs/learning-powerShell/powershell-beginners-guide.md b/docs/learning-powershell/powershell-beginners-guide.md similarity index 100% rename from docs/learning-powerShell/powershell-beginners-guide.md rename to docs/learning-powershell/powershell-beginners-guide.md diff --git a/docs/learning-powerShell/using-ise.md b/docs/learning-powershell/using-ise.md similarity index 100% rename from docs/learning-powerShell/using-ise.md rename to docs/learning-powershell/using-ise.md diff --git a/docs/learning-powerShell/using-vscode.md b/docs/learning-powershell/using-vscode.md similarity index 100% rename from docs/learning-powerShell/using-vscode.md rename to docs/learning-powershell/using-vscode.md diff --git a/docs/learning-powerShell/vscode.png b/docs/learning-powershell/vscode.png similarity index 100% rename from docs/learning-powerShell/vscode.png rename to docs/learning-powershell/vscode.png From 32b7d8cb9952d2078b665558ea445f55938c1f19 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:43:33 -0700 Subject: [PATCH 2/9] Make learning-powershell.md the tree's README.md --- docs/learning-powershell/{learning-powershell.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/learning-powershell/{learning-powershell.md => README.md} (100%) diff --git a/docs/learning-powershell/learning-powershell.md b/docs/learning-powershell/README.md similarity index 100% rename from docs/learning-powershell/learning-powershell.md rename to docs/learning-powershell/README.md From 886dea5cb5caeb2b001ca19203deea1242ed3d5c Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:47:03 -0700 Subject: [PATCH 3/9] Rewrite README --- README.md | 129 +++++++++++++++++++++++++++--------------------------- 1 file changed, 65 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 89174fd4d..cb1eb463b 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,103 @@ -![PowerShell Logo](assets/Powershell_64.png) PowerShell -======================== +![logo][] PowerShell +==================== -PowerShell is a task automation and configuration management platform, -consisting of a command-line shell and associated scripting language built -using the [.NET Command-Line Interface](https://github.com/dotnet/cli). -PowerShell provides full access to COM and WMI, enabling administrators to -automate administrative tasks on both local and remote Windows, Linux, and OS X systems. +PowerShell is a task automation and configuration management platform. +It consists of a cross-platform command-line shell and associated scripting language. + +[logo]: assets/Powershell_64.png New to PowerShell? ------------------ -If you are new to PowerShell and would like to learn more, we recommend -reviewing the [getting started documentation][getting-started]. -[getting-started]: docs/learning-powerShell/learning-powershell.md +If you are new to PowerShell and would like to learn more, we recommend reviewing the [getting started][] documentation. -Build Status ------------- - -| Platform | `master` | -|--------------|----------| -| Ubuntu 14.04 | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell) | -| OS X 10.11 | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell) | -| Windows | [![Build status](https://ci.appveyor.com/api/projects/status/jtefab3hpngtyesp/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell/branch/master) | +[getting started]: docs/learning-powershell Get PowerShell -------------- -1. Download the package for your platform at [PowerShell Releases][releases]. -1. Install the package. - * [Linux or OS X][inst-linux]. - * [Windows][inst-win]. +You can download and install a PowerShell package for any of the following platforms. +Our packages are hosted on the GitHub [releases][] page. -Building PowerShell -------------------- +| **Platform** | [Releases][] | Build status | +|--------------|---------------------------------------------------|--------------------------| +| Windows | [.msi][rl-windows] [(how to install)][in-windows] | [![av-image][]][av-site] | +| Ubuntu 14.04 | [.deb][rl-ubuntu] [(how to install)][in-ubuntu] | [![tv-image][]][tv-site] | +| CentOS 7 | [.rpm][rl-centos] [(how to install)][in-centos] | *N/A* | +| OS X 10.11 | [.pkg][rl-osx] [(how to install)][in-osx] | [![tv-image][]][tv-site] | -| Linux | Windows | OS X | -|-------|----------|------| -| [Instructions][build-linux] | [Instructions][build-wc] | [Instructions][build-osx] | +[releases]: https://github.com/PowerShell/PowerShell/releases +[rl-windows]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/PowerShell_6.0.0.7.msi +[rl-ubuntu]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell_6.0.0-alpha.7-1_amd64.deb +[rl-centos]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell-6.0.0_alpha.7-1.x86_64.rpm +[rl-osx]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell-6.0.0-alpha.7.pkg + +[installation]: docs/installation +[in-windows]: docs/installation/windows.md#msi +[in-ubuntu]: docs/installation/linux.md#ubuntu-1404 +[in-centos]: docs/installation/linux.md#centos-7 +[in-osx]: docs/installation/linux.md#os-x-1011 + +[tv-image]: https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master +[tv-site]: https://travis-ci.com/PowerShell/PowerShell/branches +[av-image]: https://ci.appveyor.com/api/projects/status/jtefab3hpngtyesp/branch/master?svg=true +[av-site]: https://ci.appveyor.com/project/PowerShell/powershell/branch/master + +Building the Repository +----------------------- + +Please refer to the platform-specific [build][] documentation. + +| Linux | Windows | OS X | +|--------------------------|----------------------------|------------------------| +| [Instructions][bd-linux] | [Instructions][bd-windows] | [Instructions][bd-osx] | + +[build]: docs/building +[bd-linux]: docs/building/linux.md +[bd-windows]: docs/building/windows-core.md +[bd-osx]: docs/building/osx.md Downloading the Source Code ----------------------- +--------------------------- + The PowerShell repository has a number of other repositories embedded as submodules. -To make things easy, we can just clone recursively. + +To make things easy, we can just clone recursively: ```sh git clone --recursive https://github.com/PowerShell/PowerShell.git ``` If you already cloned but forgot to use `--recursive`, you can update submodules manually: + ```sh -git submodule init -git submodule update +git submodule update --init ``` + See [working with the PowerShell repository][powershell-repo-101] for more information. +[powershell-repo-101]: docs/git/powershell-repository-101.md + Developing and Contributing -------------------------- -Please see the [Contribution Guide][contribution] for how to develop and contribute. +Please see the [Contribution Guide][] for how to develop and contribute. -If you encounter issues in your development, please consult the [known issues][known-issues] -and [FAQ][faq] documents to see if the issue you are running into is -captured and if a workaround exists. +If you have any problems, please consult the [known issues][], developer [FAQ][], and [GitHub issues][]. +If you do not see your problem captured, please file a [new issue][] and follow the provided template. -If you encounter issues with PowerShell itself, first search for it in our [issues][github-issues]. -If you do not see your issue captured, please file a [new issue][new-issue]. For more details see [Contributing to issues][contribution-issues]. - -PowerShell Community --------------------- -`TODO` Missing community details - -Legal and Licensing -------------------- - -`TODO` Missing license details - -`TODO` Missing link to contributor agreement +[Contribution Guide]: .github/CONTRIBUTING.md +[known issues]: docs/KNOWNISSUES.md +[FAQ]: docs/FAQ.md +[GitHub issues]: https://github.com/PowerShell/PowerShell/issues +[new issue]:https://github.com/PowerShell/PowerShell/issues/new Code of Conduct --------------- This project has adopted the [Microsoft Open Source Code of Conduct][conduct-code]. -For more information see the [Code of Conduct FAQ][conduct-FAQ] or contact -[opencode@microsoft.com][conduct-email] with any additional questions or comments. +For more information see the [Code of Conduct FAQ][conduct-FAQ] or contact [opencode@microsoft.com][conduct-email] with any additional questions or comments. -[build-linux]: docs/building/linux.md -[build-osx]: docs/building/osx.md -[build-wc]: docs/building/windows-core.md [conduct-code]: http://opensource.microsoft.com/codeofconduct/ -[conduct-email]: mailto:opencode@microsoft.com [conduct-FAQ]: http://opensource.microsoft.com/codeofconduct/faq/ -[contribution]: .github/CONTRIBUTING.md -[contribution-issues]: .github/CONTRIBUTING.md#contributing-to-issues -[faq]: docs/FAQ.md -[github-issues]:https://github.com/PowerShell/PowerShell/issues -[inst-linux]: docs/installation/linux.md -[inst-win]: docs/installation/windows.md -[known-issues]: docs/KNOWNISSUES.md -[new-issue]:https://github.com/PowerShell/PowerShell/issues/new -[releases]: https://github.com/PowerShell/PowerShell/releases -[powershell-repo-101]: docs/git/powershell-repository-101.md +[conduct-email]: mailto:opencode@microsoft.com From 1dc788897f8e6cdac2bdc20343001337f4f59c3c Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:47:34 -0700 Subject: [PATCH 4/9] Make maintainers.md the tree's README.md --- docs/maintainers/{maintainers.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/maintainers/{maintainers.md => README.md} (100%) diff --git a/docs/maintainers/maintainers.md b/docs/maintainers/README.md similarity index 100% rename from docs/maintainers/maintainers.md rename to docs/maintainers/README.md From a5d655c998818ddacf9615c58f3e6f0accf3c1c8 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:47:54 -0700 Subject: [PATCH 5/9] Consolidate releasing and maintainers docs --- docs/{releasing/README.md => maintainers/releasing.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{releasing/README.md => maintainers/releasing.md} (100%) diff --git a/docs/releasing/README.md b/docs/maintainers/releasing.md similarity index 100% rename from docs/releasing/README.md rename to docs/maintainers/releasing.md From f63da502e1f7881afd50270eb8928b880f10e96f Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 14:51:18 -0700 Subject: [PATCH 6/9] Make 101.md the tree's README.md --- README.md | 4 +--- docs/git/{powershell-repository-101.md => README.md} | 0 2 files changed, 1 insertion(+), 3 deletions(-) rename docs/git/{powershell-repository-101.md => README.md} (100%) diff --git a/README.md b/README.md index cb1eb463b..5afd2e44d 100644 --- a/README.md +++ b/README.md @@ -74,9 +74,7 @@ If you already cloned but forgot to use `--recursive`, you can update submodules git submodule update --init ``` -See [working with the PowerShell repository][powershell-repo-101] for more information. - -[powershell-repo-101]: docs/git/powershell-repository-101.md +See [working with the PowerShell repository](docs/git) for more information. Developing and Contributing -------------------------- diff --git a/docs/git/powershell-repository-101.md b/docs/git/README.md similarity index 100% rename from docs/git/powershell-repository-101.md rename to docs/git/README.md From 6e44b52c92440815bfb57fa39f153a767f05930e Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 16:31:07 -0700 Subject: [PATCH 7/9] Update contributing guidelines * Links fixed. * Link to maintainers removed; superfluous in this document. * TODO added to changelog. (I don't like this but was hesitant to remove it). * Periods and spelling fixed. --- .github/CONTRIBUTING.md | 262 +++++++++++++++++++++++++++------------- 1 file changed, 180 insertions(+), 82 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f5e3d7c09..63b417213 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,48 +1,61 @@ Contribute to PowerShell -================================= +======================== -We welcome and appreciate contributions from the community. There are many ways to become involved with PowerShell, including filing issues, joining in design conversations, -writing and improving documentation, contributing to the code. Please read the rest of this document to ensure a smooth contribution process. +We welcome and appreciate contributions from the community. +There are many ways to become involved with PowerShell: +including filing issues, +joining in design conversations, +writing and improving documentation, +and contributing to the code. +Please read the rest of this document to ensure a smooth contribution process. New to Git? ----- -- Make sure you have a [GitHub account](https://github.com/signup/free) -- Learning Git: - * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources] - * [Git Basics](../docs/git/basics.md): install and getting started. -- [GitHub Flow Guide](https://guides.github.com/introduction/flow/): step-by-step instructions of GitHub flow. +----------- -Quick Start Check-list ----- -- Review the [Contribution License Agreement][CLA] requriement. -- Get familiar with the [PowerShell repository](../docs/git/powershell-repository-101.md) +* Make sure you have a [GitHub account](https://github.com/signup/free). +* Learning Git: + * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources]. + * [Git Basics](../docs/git/basics.md): + install and getting started. +* [GitHub Flow Guide](https://guides.github.com/introduction/flow/): + step-by-step instructions of GitHub flow. + +Quick Start Checklist +--------------------- + +* Review the [Contribution License Agreement][CLA] requirement. +* Get familiar with the [PowerShell repository](../docs/git). Contributing to Issues ----- +---------------------- -- Review the [Issue Label Descriptions](../docs/dev-process/issue-label-descriptions.md) -- Check if the issue you are going to file already exists in our [GitHub issues][open-issue]. -- If you can't find your issue already, [open a new issue](https://github.com/PowerShell/PowerShell/issues/new), making sure to follow the directions as best you can. -- If the issue is marked as [`Help Wanted`][help-wanted-issue], the PowerShell [maintainers][maintainers] are looking for help with the issue. +* Review the [Issue Label Descriptions](../docs/dev-process/issue-label-descriptions.md). +* Check if the issue you are going to file already exists in our [GitHub issues][open-issue]. +* If you can't find your issue already, + [open a new issue](https://github.com/PowerShell/PowerShell/issues/new), + making sure to follow the directions as best you can. +* If the issue is marked as [`Help Wanted`][help-wanted-issue], + the PowerShell maintainers are looking for help with the issue. Contributing to Documentation ----- +----------------------------- + ### Contributing to documentation related to the PowerShell the product Please see the [Contributor Guide in `PowerShell/PowerShell-Docs`](https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md). ### Contributing to documentation related to contributing or maintaining the PowerShell Project -- When appropriate in writting markdown docs, use [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). - In most cases, it means "once sentence per line". -- Otherwise, these issues should be treated like any other issue in this repo. See [Contribuing to Code](#contributing-to-code). +* When writing Markdown documentation, use [semantic linefeeds][]. + In most cases, it means "once clause / idea per line". +* Otherwise, these issues should be treated like any other issue in this repo. Contributing to Code ----- +-------------------- ### Building and testing #### Building PowerShell -Please see [Building PowerShell](../README.md#building-powershell) +Please see [Building PowerShell](../README.md#building-the-repository). #### Testing PowerShell Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test you build locally. @@ -54,11 +67,13 @@ Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running ### Forks and Pull Requests GitHub fosters collaboration through the notion of [pull requests][using-prs]. -On GitHub, anyone can [fork][fork-a-repo] an existing repository into their own branch where they can make private changes to the original repository. -To contribute these changes back into the original repository, a user simply creates a pull request in order to "request" that the changes be taken "upstream". +On GitHub, anyone can [fork][fork-a-repo] an existing repository +into their own user account, where they can make private changes to their fork. +To contribute these changes back into the original repository, +a user simply creates a pull request in order to "request" that the changes be taken "upstream". Additional references: -* GitHub's guide on [forking project](https://guides.github.com/activities/forking/) +* GitHub's guide on [forking](https://guides.github.com/activities/forking/) * GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request) * GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) @@ -66,104 +81,188 @@ Additional references: ### Lifecycle of a pull request #### Pull request submission + **Always create a pull request to the `master` branch of this repository**. -For more information, learn about our [branch structure][branch-structure]. ![Github-PR-dev.png](Images/Github-PR-dev.png) -* If your contribution in a way that changes the user or developer experience, you are expected to document those changes. See [Contributing to documentation related to the PowerShell the product](#contributing-to-documentation-related-to-the-powershell-the-product) +* If your contribution in a way that changes the user or developer experience, + you are expected to document those changes. + See [Contributing to documentation related to the PowerShell the product](#contributing-to-documentation-related-to-the-powershell-the-product). -* Add a meaningful title of the PR describing what change you want to check in. Don't simply put: "Fixes issue #5". A better example is: "Added Ensure parameter to New-Item CmdLet. Fixes #5". +* Add a meaningful title of the PR describing what change you want to check in. + Don't simply put: "Fixes issue #5". + A better example is: "Add Ensure parameter to New-Item cmdlet", with "Fixes #5" in the PR's body. -* When you create a pull request, fill out the pull request template including a summary of what's included in your changes. -If the changes are related to an existing GitHub issue, please reference the issue in pull request title or description (e.g. ```Closes #11```). See [this][closing-via-message] for more details. +* When you create a pull request, + fill out the pull request template, + including a summary of what's included in your changes. + If the changes are related to an existing GitHub issue, + please reference the issue in pull request description (e.g. ```Closes #11```). + See [this][closing-via-message] for more details. -* Include an update to the [change log](../CHANGELOG.MD) file in your pull request to reflect changes for future versions changelog. Put them in `Unreleased` section (create one if doesn't exist). This would simplify the release process for [maintainers][maintainers]. Example: +* Include an update to the [changelog](../CHANGELOG.MD) in your pull request. + New changes always go into the **Unreleased** section. + Keeping the changelog up-to-date simplifies the release process for maintainers. + An example: ``` - ## Versions + Unreleased + ---------- - ### Unreleased - - - Added support for `-FriendlyName` in `Update-Item`. + * `Update-Item` now supports `-FriendlyName`. ``` - Please use past tense when describing your changes: + Please use the present tense and imperative mood when describing your changes: - * Instead of "Adding support for Windows Server 2012 R2", write "Added support for Windows Server 2012 R2". + * Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2". - * Instead of "Fix for server connection issue", write "Fixed server connection issue". - - Also, if change is related to specific resource, please prefix the description with the resource name: - - * Instead of "New parameter 'ConnectionCredential' in New-SqlConnection", write "New-SqlConnection: added parameter 'ConnectionCredential'" + * Instead of "Fixed for server connection issue", write "Fix server connection issue". -#### Pull request - Automatic checks + This form is akin to giving commands to the code base, + and is recommended by the Git SCM developers. + It is also used in the [Git commit messages](#common-engineering-practices). + + Also, if change is related to a specific resource, please prefix the description with the resource name: -* If this is your first contribution to PowerShell, you may be asked to sign a [Contribution Licensing Agreement][CLA] (CLA) before your changes will be accepted. -* Make sure you follow the [Common Engineering Practices](#common-engineering-practices) and [testing guidelines](../docs/testing-guidelines/testing-guidelines.md) -* After submitting your pull request, our [CI system (Travis-CI & Appveyor)][ci-system] will run a suite of tests and automatically update the status of the pull request. + * Instead of "New,parameter 'ConnectionCredential' in New-SqlConnection", + write "New-SqlConnection: added parameter 'ConnectionCredential'". -#### Pull request - Code review +#### Pull Request - Automatic Checks + +* If this is your first contribution to PowerShell, + you may be asked to sign a [Contribution Licensing Agreement][CLA] (CLA) + before your changes will be accepted. -* After a successful test pass, the area [maintainers][maintainers] will do a code review, commenting on any changes that might need to be made. If you are not designated as an area's [maintainer][maintainers], feel free to review others' Pull Requests as well. Additional feedback is always welcome (leave your comments even if everything looks good - simple "Looks good to me" or "LGTM" will suffice so that we know someone has already taken a look at it)! -* Once the code review is done, all merge conflicts are resolved, and the CI system build status is passing, a [maintainer][maintainers] will merge your changes. +* Make sure you follow the [Common Engineering Practices](#common-engineering-practices) + and [testing guidelines](../docs/testing-guidelines/testing-guidelines.md). + +* After submitting your pull request, + our [CI system (Travis CI and AppVeyor)][ci-system] + will run a suite of tests and automatically update the status of the pull request. + +#### Pull Request / Code Review + +* After a successful test pass, + the area maintainers will do a code review, + commenting on any changes that might need to be made. + +* Additional feedback is always welcome! + Even if you are not designated as an area's maintainer, + feel free to review others' pull requests anyway. + Leave your comments even if everything looks good; + a simple "Looks good to me" or "LGTM" will suffice. + This way we know someone has already taken a look at it! + +* Once the code review is done, + all merge conflicts are resolved, + and the CI system build status is passing, + a maintainer will merge your changes. + +* For more information on the the PowerShell maintainers' process, + see the [documentation](../docs/maintainers). Making Breaking Changes ----- +----------------------- -When you make code changes, please pay attention to these that can affect the [Public Contract](../docs/dev-process/breaking-change-contract.md), -for example, PowerShell parameter, API or protocols changes. Before making changes to the code, first review the [breaking changes contract](../docs/dev-process/breaking-change-contract.md) +When you make code changes, +please pay attention to these that can affect the [Public Contract](../docs/dev-process/breaking-change-contract.md). +For example, changing PowerShell parameters, APIs, or protocols break the public contract. +Before making changes to the code, +first review the [breaking changes contract](../docs/dev-process/breaking-change-contract.md) and follow the guidelines to keep PowerShell backward compatible. Making Design Changes ----- -To add new features such as CmdLets or making design changes, please follow the [PowerShell Request for Comments (RFC)](https://github.com/PowerShell/PowerShell-RFC) process. +--------------------- + +To add new features such as cmdlets or making design changes, +please follow the [PowerShell Request for Comments (RFC)](https://github.com/PowerShell/PowerShell-RFC) process. Common Engineering Practices ----- -Other than the guidelines for ([coding](../docs/coding-guidelines/coding-guidelines.md), -the [RFC process](https://github.com/PowerShell/PowerShell-RFC) for design, [documentation](#contributing-to-documentation) -and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, we encourage contributors to follow these common engineering practices: +---------------------------- -- Format commit messages based on [Tim Pope's guidelines]("http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html"): +Other than the guidelines for ([coding](../docs/coding-guidelines/coding-guidelines.md), +the [RFC process](https://github.com/PowerShell/PowerShell-RFC) for design, +[documentation](#contributing-to-documentation) and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, +we encourage contributors to follow these common engineering practices: + +* Format commit messages following these guidelines: ``` Summarize change in 50 characters or less -Provide more detail after the first line. Leave one blank line below the -summary and wrap all lines at 72 characters or less. +Similar to email, this is the body of the commit message, +and the above is the subject. +Always leave a single blank line between the subject and the body +so that `git log` and `git rebase` work nicely. -If the change fixes an issue, leave another blank line after the final -paragraph and indicate which issue the change fixes in the specific format below. +The subject of the commit should use the present tense and +imperative mood, like issuing a command: -Fix #42 +> Makes abcd do wxyz + +The body should be a useful message explaining +why the changes were made. + +If significant alternative solutions were available, +explain why they were discarded. + +Keep in mind that the person most likely to refer to your commit message +is you in the future, so be detailed! + +As Git commit messages are most frequently viewed in the terminal, +you should wrap all lines around 72 characters. + +Using semantic line feeds (breaks that separate ideas) +is also appropriate, as is using Markdown syntax. ``` -- Don't commit code that you didn't write. If you find code that you think is a good fit to add to PowerShell, file an issue and start a discussion before proceeding -- Create and/or update tests when making code changes -- Run tests and ensure they are passing before pull request -- All pull requests **must** pass CI systems before they can be approved -- Avoid making big pull requests. Instead, file an issue and start a discussion with the community before you invest a large amount of time -- Blog and tweet about your contributions frequently! +* These are based on Tim Pope's [guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), + Git SCM [submitting patches](https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches), + Brandon Rhodes' [semantic linefeeds][], + and John Gruber's [Markdown syntax](https://daringfireball.net/projects/markdown/syntax). + +* Don't commit code that you didn't write. + If you find code that you think is a good fit to add to PowerShell, + file an issue and start a discussion before proceeding. + +* Create and/or update tests when making code changes. + +* Run tests and ensure they are passing before pull request. + +* All pull requests **must** pass CI systems before they can be approved. + +* Avoid making big pull requests. + Before you invest a large amount of time, + file an issue and start a discussion with the community. File Headers ----- -The following file header is used for all PowerShell code. Please use it for new files. For more information, see [coding guidelines](../docs/coding-guidelines/coding-guidelines.md). +------------ + +The following file header is used for all PowerShell code. +Please use it for new files. +For more information, see [coding guidelines](../docs/coding-guidelines/coding-guidelines.md). + ```C# // … TODO TODO // Licensed to the PowerShell …. under one or more agreements. // See the LICENSE file in the project root for more information. ``` -Licensing & Copyright ----- +Licensing and Copyright +----------------------- + You can find more information about the PowerShell source license and copyright [here](../docs/community/legal-licensing.md). Contributor License Agreement (CLA) ----- +----------------------------------- -To speed up the acceptance of any contribution to any PowerShell repositories, you could [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) ahead of time. -If you've already contributed to PowerShell repositories in the past, congratulations! You've already completed this step. This a one-time requirement for the PowerShell project. -Signing the CLA process is simple and can be done in less than a minute. You don't have to do this up-front. You can simply clone, fork, and submit your pull request as usual. +To speed up the acceptance of any contribution to any PowerShell repositories, +you could [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) ahead of time. +If you've already contributed to PowerShell repositories in the past, congratulations! +You've already completed this step. +This a one-time requirement for the PowerShell project. +Signing the CLA process is simple and can be done in less than a minute. +You don't have to do this up-front. +You can simply clone, fork, and submit your pull request as usual. When your pull request is created, it is classified by a CLA bot. If the change is trivial, it's classified as `cla-required`. Once you sign a CLA, all your existing and future pull requests will be labeled as `cla-signed`. @@ -174,12 +273,11 @@ Once you sign a CLA, all your existing and future pull requests will be labeled [governance]: ../docs/community/governance.md [using-prs]: https://help.github.com/articles/using-pull-requests/ [fork-a-repo]: https://help.github.com/articles/fork-a-repo/ -[branch-structure]: tbd [closing-via-message]: https://help.github.com/articles/closing-issues-via-commit-messages/ [CLA]: #contributor-license-agreement-cla [ci-system]: ../docs/testing-guidelines/testing-guidelines.md#ci-system [good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/ [contribute-issues]: #contributing-to-issues [open-issue]: https://github.com/PowerShell/PowerShell/issues -[maintainers]: ../docs/maintainers/maintainers.md [help-wanted-issue]: https://github.com/PowerShell/PowerShell/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22 +[semantic linefeeds]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ From ba5bcbc8f370bd108388d72e51fbc07394de0640 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 17:57:34 -0700 Subject: [PATCH 8/9] Update releasing documentation --- docs/maintainers/releasing.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/maintainers/releasing.md b/docs/maintainers/releasing.md index 53bee6eee..710434b60 100644 --- a/docs/maintainers/releasing.md +++ b/docs/maintainers/releasing.md @@ -2,22 +2,32 @@ Preparing ========= PowerShell releases use [Semantic Versioning][semver]. -Until we hit 1.0, each sprint results in a bump to the minor version number, -and interim bugfix releases bump the patch number. +Until we hit 6.0, each sprint results in a bump to the build number, +so `v6.0.0-alpha.7` goes to `v6.0.0-alpha.8`. -When a particular commit is chosen as a release, we create an [annotated tag][tag] that names the release, +When a particular commit is chosen as a release, +we create an [annotated tag][tag] that names the release, and list the major changes since the previous release. -An annotated tag has a message (like a commit), and is *not* the same as a lightweight tag. -Create one with `git tag -a vX.Y.Z`. +An annotated tag has a message (like a commit), +and is *not* the same as a lightweight tag. +Create one with `git tag -a v6.0.0-alpha.7`. Our convention is to prepend the `v` to the semantic version. The summary (first line) of the annotated tag message should be the full release title, -e.g. 'v0.6.0 beta release of Open PowerShell'. +e.g. 'v6.0.0-alpha.7 release of PowerShell'. When the annotated tag is finalized, push it with `git push --tags`. GitHub will see the tag and present it as an option when creating a new [release][]. Start the release, use the annotated tag's summary as the title, and save the release as a draft while you upload the binary packages. +Just as important as creating the release is updating the links on our readme, +and the package names in the installation instructions. +The AppVeyor build number should also be incremented. + +While it is not a big concern for developer previews, +the official releases should be created on dedicated machines +such that the debug symbols do not contain personal machine paths. + [semver]: http://semver.org/ [tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging [release]: https://help.github.com/articles/creating-releases/ @@ -34,11 +44,8 @@ The output *must* be published so that it includes the runtime. This function will automatically deduce the correct version from the most recent annotated tag (using `git describe`), and if not specified, will build a package for the current platform. -At this time, Linux packages must be built on Linux, and OS X packages on OS X; -however, an RPM can be created on Ubuntu. -This requires installing the `rpm` package, building with `-Runtime centos.7.1-x64`, and packaging with `-Type rpm`. - -The `Start-PSBuild` function relies on the [Effing Package Management][fpm] project, +At this time, each package must be made on the corresponding platform. +The `Start-PSBuild` function relies on the [Effing Package Management][fpm] project, which makes building packages for any (non-Windows) platform a breeze. Follow their readme to install FPM. From ba6b9663fb611b2629af8aeb0a7aa719a7402933 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Thu, 28 Jul 2016 12:45:31 -0700 Subject: [PATCH 9/9] Move build badges * Remove superfluous link to releases page * Remove superfluous link to docs/build * Add column back for install instructions * Add extra link to the FAQ --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5afd2e44d..0ef7d602c 100644 --- a/README.md +++ b/README.md @@ -17,16 +17,14 @@ Get PowerShell -------------- You can download and install a PowerShell package for any of the following platforms. -Our packages are hosted on the GitHub [releases][] page. -| **Platform** | [Releases][] | Build status | -|--------------|---------------------------------------------------|--------------------------| -| Windows | [.msi][rl-windows] [(how to install)][in-windows] | [![av-image][]][av-site] | -| Ubuntu 14.04 | [.deb][rl-ubuntu] [(how to install)][in-ubuntu] | [![tv-image][]][tv-site] | -| CentOS 7 | [.rpm][rl-centos] [(how to install)][in-centos] | *N/A* | -| OS X 10.11 | [.pkg][rl-osx] [(how to install)][in-osx] | [![tv-image][]][tv-site] | +| Platform | Releases | How to Install | +|--------------|--------------------|--------------------------------| +| Windows | [.msi][rl-windows] | [How to Install][in-windows] | +| Ubuntu 14.04 | [.deb][rl-ubuntu] | [How to Install][in-ubuntu] | +| CentOS 7 | [.rpm][rl-centos] | [How to Install][in-centos] | +| OS X 10.11 | [.pkg][rl-osx] | [How to Install][in-osx] | -[releases]: https://github.com/PowerShell/PowerShell/releases [rl-windows]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/PowerShell_6.0.0.7.msi [rl-ubuntu]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell_6.0.0-alpha.7-1_amd64.deb [rl-centos]: https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-alpha.7/powershell-6.0.0_alpha.7-1.x86_64.rpm @@ -38,25 +36,33 @@ Our packages are hosted on the GitHub [releases][] page. [in-centos]: docs/installation/linux.md#centos-7 [in-osx]: docs/installation/linux.md#os-x-1011 -[tv-image]: https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master -[tv-site]: https://travis-ci.com/PowerShell/PowerShell/branches -[av-image]: https://ci.appveyor.com/api/projects/status/jtefab3hpngtyesp/branch/master?svg=true -[av-site]: https://ci.appveyor.com/project/PowerShell/powershell/branch/master Building the Repository ----------------------- -Please refer to the platform-specific [build][] documentation. - | Linux | Windows | OS X | |--------------------------|----------------------------|------------------------| | [Instructions][bd-linux] | [Instructions][bd-windows] | [Instructions][bd-osx] | -[build]: docs/building +If you have any problems building, please consult the developer [FAQ][]. + +### Build status of master branches + +| AppVeyor (Windows) | Travis CI (Linux / OS X) | +|--------------------------|--------------------------| +| [![av-image][]][av-site] | [![tv-image][]][tv-site] | + [bd-linux]: docs/building/linux.md [bd-windows]: docs/building/windows-core.md [bd-osx]: docs/building/osx.md +[FAQ]: docs/FAQ.md + +[tv-image]: https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master +[tv-site]: https://travis-ci.com/PowerShell/PowerShell/branches +[av-image]: https://ci.appveyor.com/api/projects/status/jtefab3hpngtyesp/branch/master?svg=true +[av-site]: https://ci.appveyor.com/project/PowerShell/powershell/branch/master + Downloading the Source Code --------------------------- @@ -86,7 +92,6 @@ If you do not see your problem captured, please file a [new issue][] and follow [Contribution Guide]: .github/CONTRIBUTING.md [known issues]: docs/KNOWNISSUES.md -[FAQ]: docs/FAQ.md [GitHub issues]: https://github.com/PowerShell/PowerShell/issues [new issue]:https://github.com/PowerShell/PowerShell/issues/new