Trim the main README.md

CONTRIBUTING.md

@@ -1,3 +1,9 @@
-Please see our Instructions for Contributing in the [README](https://github.com/App-vNext/Polly#instructions-for-contributing) and [wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow).
+# Contributing
 
-Please be sure to branch from the head of the default branch when developing contributions.  
+Please be sure to branch from the head of the default branch when developing contributions.
+
+For GitHub workflow, check out our [Wiki](https://github.com/App-vNext/Polly/wiki/Git-Workflow).
+
+Since Polly is part of the .NET Foundation, we ask our contributors to abide by their [Code of Conduct](https://www.dotnetfoundation.org/code-of-conduct). To contribute (beyond trivial typo corrections), review and sign the [.NET Foundation Contributor License Agreement](https://cla.dotnetfoundation.org/). This ensures the community is free to use your contributions.  The registration process can be completed entirely online.
+
+Also, we've stood up a [Slack](http://www.pollytalk.org) channel for easier real-time discussion of ideas and the general direction of Polly as a whole. Be sure to [join the conversation](http://www.pollytalk.org) today!.

docs/README.md

@@ -0,0 +1,11 @@
+# Polly Documentation
+
+If you're already familiar with the [basic features](../README.md) of Polly, delve deeper into its advanced functionalities here.
+
+## Table of Contents
+
+- [Extensibility](v7/extensibility.md): Learn how you can extend Polly with new policies.
+- [Polly-Contrib](polly-contrib.md): Learn how to contribute to and extend the Polly ecosystem.
+- [Simmy](simmy.md): Get to know chaos engineering via Polly's capabilities.
+- [Third-Party Libraries and Contributions](libraries-and-contributions.md): Find out which libraries Polly depends on and who contributes to its development.
+- [Additional Resources](resources.md): Browse through blogs, podcasts, courses, e-books, and other community resources.

docs/libraries-and-contributions.md

@@ -0,0 +1,80 @@
+# 3rd Party Libraries and Contributions
+
+- [Fluent Assertions](https://github.com/fluentassertions/fluentassertions) - A set of .NET extension methods that allow you to more naturally specify the expected outcome of a TDD or BDD-style test | [Apache License 2.0 (Apache)](https://github.com/dennisdoomen/fluentassertions/blob/develop/LICENSE)
+- [xUnit.net](https://github.com/xunit/xunit) - Free, open source, community-focused unit testing tool for the .NET Framework | [Apache License 2.0 (Apache)](https://github.com/xunit/xunit/blob/main/license.txt)
+- [Ian Griffith's TimedLock](http://www.interact-sw.co.uk/iangblog/2004/04/26/yetmoretimedlocking)
+- [Steven van Deursen's ReadOnlyDictionary](http://www.cuttingedge.it/blogs/steven/pivot/entry.php?id=29) (until Polly v5.0.6)
+- [Stephen Cleary's AsyncEx library](https://github.com/StephenCleary/AsyncEx) for AsyncSemaphore (supports BulkheadAsync policy for .NET4.0 only) (until Polly v5.9.0) | [MIT license](https://github.com/StephenCleary/AsyncEx/blob/master/LICENSE)
+- [@theraot](https://github.com/theraot)'s [ExceptionDispatchInfo implementation for .NET4.0](https://stackoverflow.com/a/31226509/) (supports Timeout policy for .NET4.0 only) (until Polly v5.9.0) including also a contribution by [@migueldeicaza](https://github.com/migueldeicaza) | Licensed under and distributed under [Creative Commons Attribution Share Alike license](https://creativecommons.org/licenses/by-sa/3.0/) per [StackExchange Terms of Service](https://stackexchange.com/legal)
+- Build powered by [Cake](https://cakebuild.net/) and [MinVer](https://github.com/adamralph/minver).  Developers powered by [Resharper](https://www.jetbrains.com/resharper/), with thanks to JetBrains for [OSS licensing](https://www.jetbrains.com/support/community/#section=open-source).
+
+## Acknowledgements
+
+- [lokad-shared-libraries](https://github.com/Lokad/lokad-shared-libraries) - Helper assemblies originally for .NET 3.5 and Silverlight 2.0 which were developed as part of the Open Source effort by Lokad.com (discontinued) | [New BSD License](https://raw.github.com/Lokad/lokad-shared-libraries/master/Lokad.Shared.License.txt)
+- [@michael-wolfenden](https://github.com/michael-wolfenden) - The creator and mastermind of Polly!
+- [@ghuntley](https://github.com/ghuntley) - Portable Class Library implementation.
+- [@mauricedb](https://github.com/mauricedb) - Initial async implementation.
+- [@robgibbens](https://github.com/RobGibbens) - Added existing async files to PCL project
+- [Hacko](https://github.com/hacko-bede) - Added extra `NotOnCapturedContext` call to prevent potential deadlocks when blocking on asynchronous calls
+- [@ThomasMentzel](https://github.com/ThomasMentzel) - Added ability to capture the results of executing a policy via `ExecuteAndCapture`
+- [@yevhen](https://github.com/yevhen) - Added full control of whether to continue on captured synchronization context or not
+- [@reisenberger](https://github.com/reisenberger) - Added full async cancellation support
+- [@reisenberger](https://github.com/reisenberger) - Added async support for ContextualPolicy
+- [@reisenberger](https://github.com/reisenberger) - Added ContextualPolicy support for circuit-breaker
+- [@reisenberger](https://github.com/reisenberger) - Extended circuit-breaker for public monitoring and control
+- [@reisenberger](https://github.com/reisenberger) - Added ExecuteAndCapture support with arbitrary context data
+- [@kristianhald](https://github.com/kristianhald) and [@reisenberger](https://github.com/reisenberger) - Added AdvancedCircuitBreaker
+- [@reisenberger](https://github.com/reisenberger) - Allowed async onRetry delegates to async retry policies
+- [@Lumirris](https://github.com/Lumirris) - Add new Polly.Net40Async project/package supporting async for .NET40 via Microsoft.Bcl.Async
+- [@SteveCote](https://github.com/SteveCote) - Added overloads to WaitAndRetry and WaitAndRetryAsync methods that accept an onRetry delegate which includes the attempt count.
+- [@reisenberger](https://github.com/reisenberger) - Allowed policies to handle returned results; added strongly-typed policies Policy<TResult>;.
+- [@christopherbahr](https://github.com/christopherbahr) - Added optimisation for circuit-breaker hot path.
+- [@Finity](https://github.com/Finity) - Fixed circuit-breaker threshold bug.
+- [@reisenberger](https://github.com/reisenberger) - Add some missing ExecuteAndCapture/Async overloads.
+- [@brunolauze](https://github.com/brunolauze) - Add CancellationToken support to synchronous executions (to support TimeoutPolicy).
+- [@reisenberger](https://github.com/reisenberger) - Add PolicyWrap.
+- [@reisenberger](https://github.com/reisenberger) - Add Fallback policy.
+- [@reisenberger](https://github.com/reisenberger) - Add PolicyKeys and context to all policy executions, as bedrock for policy events and metrics tracking executions.
+- [@reisenberger](https://github.com/reisenberger),  and contributions from [@brunolauze](https://github.com/brunolauze) -  Add Bulkhead Isolation policy.
+- [@reisenberger](https://github.com/reisenberger) - Add Timeout policy.
+- [@reisenberger](https://github.com/reisenberger) - Fix .NETStandard 1.0 targeting.  Remove PCL259 target.  PCL259 support is provided via .NETStandard1.0 target, going forward.
+- [@reisenberger](https://github.com/reisenberger) - Fix CircuitBreaker HalfOpen state and cases when breakDuration is shorter than typical call timeout.  Thanks to [@vgouw](https://github.com/vgouw) and [@kharos](https://github.com/kharos) for the reports and insightful thinking.
+- [@lakario](https://github.com/lakario) - Tidy CircuitBreaker LastException property.
+- [@lakario](https://github.com/lakario) - Add NoOpPolicy.
+- [@Julien-Mialon](https://github.com/Julien-Mialon) - Fixes, support and examples for .NETStandard compatibility with Xamarin PCL projects
+- [@reisenberger](https://github.com/reisenberger) - Add mutable Context and extra overloads taking Context.  Allows different parts of a policy execution to exchange data via the mutable Context travelling with each execution.
+- [@ankitbko](https://github.com/ankitbko) - Add PolicyRegistry for storing and retrieving policies.
+- [@reisenberger](https://github.com/reisenberger) - Add interfaces by policy type and execution type.
+- [@seanfarrow](https://github.com/SeanFarrow) - Add IReadOnlyPolicyRegistry interface.
+- [@kesmy](https://github.com/Kesmy) - Migrate solution to msbuild15, banish project.json and packages.config
+- [@hambudi](https://github.com/hambudi) - Ensure sync TimeoutPolicy with TimeoutStrategy.Pessimistic rethrows delegate exceptions without additional AggregateException.
+- [@jiimaho](https://github.com/jiimaho) and [@Extremo75](https://github.com/ExtRemo75) - Provide public factory methods for PolicyResult, to support testing.
+- [@Extremo75](https://github.com/ExtRemo75) - Allow fallback delegates to take handled fault as input parameter.
+- [@reisenberger](https://github.com/reisenberger) and [@seanfarrow](https://github.com/SeanFarrow) - Add CachePolicy, with interfaces for pluggable cache providers and serializers.
+- Thanks to the awesome devs at [@tretton37](https://github.com/tretton37) who delivered the following as part of a one-day in-company hackathon led by [@reisenberger](https://github.com/reisenberger), sponsored by [@tretton37](https://github.com/tretton37) and convened by [@thecodejunkie](https://github.com/thecodejunkie)
+  - [@matst80](https://github.com/matst80) - Allow WaitAndRetry to take handled fault as an input to the sleepDurationProvider, allowing WaitAndRetry to take account of systems which specify a duration to wait as part of a fault response; eg Azure CosmosDB may specify this in `x-ms-retry-after-ms` headers or in a property to an exception thrown by the Azure CosmosDB SDK.
+  - [@MartinSStewart](https://github.com/martinsstewart) - Add GetPolicies() extension methods to IPolicyWrap.
+  - [@jbergens37](https://github.com/jbergens37) - Parallelize test running where possible, to improve overall build speed.
+- [@reisenberger](https://github.com/reisenberger) - Add new `.HandleInner<TException>(...)` syntax for handling inner exceptions natively.
+- [@rjongeneelen](https://github.com/rjongeneelen) and [@reisenberger](https://github.com/reisenberger) - Allow PolicyWrap configuration to configure policies via interfaces.
+- [@reisenberger](https://github.com/reisenberger) - Performance improvements.
+- [@awarrenlove](https://github.com/awarrenlove) - Add ability to calculate cache Ttl based on item to cache.
+- [@erickhouse](https://github.com/erickhouse) - Add a new onBreak overload that provides the prior state on a transition to an open state.
+- [@benagain](https://github.com/benagain) - Bug fix: RelativeTtl in CachePolicy now always returns a ttl relative to time item is cached.
+- [@urig](https://github.com/urig) - Allow TimeoutPolicy to be configured with Timeout.InfiniteTimeSpan.
+- [@reisenberger](https://github.com/reisenberger) - Integration with [IHttpClientFactory](https://github.com/aspnet/HttpClientFactory/) for ASPNET Core 2.1.
+- [@freakazoid182](https://github.com/Freakazoid182) - WaitAnd/RetryForever overloads where onRetry takes the retry number as a parameter.
+- [@dustyhoppe](https://github.com/dustyhoppe) - Overloads where onTimeout takes thrown exception as a parameter.
+- [@flin-zap](https://github.com/flin-zap) - Catch missing async continuation control.
+- [@reisenberger](https://github.com/reisenberger) - Clarify separation of sync and async policies.
+- [@reisenberger](https://github.com/reisenberger) - Enable extensibility by custom policies hosted external to Polly.
+- [@seanfarrow](https://github.com/SeanFarrow) - Enable collection initialization syntax for PolicyRegistry.
+- [@moerwald](https://github.com/moerwald) - Code clean-ups, usage of more concise C# members.
+- [@cmeeren](https://github.com/cmeeren) - Enable cache policies to cache values of default(TResult).
+- [@aprooks](https://github.com/aprooks) - Build script tweaks for Mac and mono.
+- [@kesmy](https://github.com/Kesmy) - Add Soucelink support, clean up cake build.
+- [@simluk](https://github.com/simluk) - Fix continueOnCaptureContext not being honored in async retry implementation (bug in v7.1.0 only).
+- [@jnyrup](https://github.com/jnyrup) - Upgrade tests to Fluent Assertions v5.9.0
+- [@SimonCropp](https://github.com/SimonCropp) - Add netcoreapp3.0 target; code clean-ups.
+- [@aerotog](https://github.com/aerotog) and [@reisenberger](https://github.com/reisenberger) - IConcurrentPolicyRegistry methods on PolicyRegistry
+- [@reisenberger](https://github.com/reisenberger) and [@martincostello](https://github.com/martincostello) - Add RateLimit policy.

docs/polly-contrib.md

@@ -0,0 +1,20 @@
+# Polly-Contrib
+
+Polly now has a [Polly-Contrib](https://github.com/Polly-Contrib) to allow the community to contribute policies or other enhancements around Polly with a low burden of ceremony.
+
+Have a contrib you'd like to publish under Polly-Contrib? Contact us with  an issue here or on [Polly's slack](http://pollytalk.slack.com), and we can set up a CI-ready Polly.Contrib repo to which you have full rights, to help you manage and deliver your awesomeness to the community!
+
+We also provide:
+
+- a blank [starter template for a custom policy](https://github.com/Polly-Contrib/Polly.Contrib.CustomPolicyTemplates) (see above for more on custom policies)
+- a [template repo for any other contrib](https://github.com/Polly-Contrib/Polly.Contrib.BlankTemplate)
+
+Both templates contain a full project structure referencing Polly, Polly's default build targets, and a build to build and test your contrib and make a NuGet package.
+
+## Available via Polly-Contrib
+
+- [Polly.Contrib.WaitAndRetry](https://github.com/Polly-Contrib/Polly.Contrib.WaitAndRetry): a collection of concise helper methods for common wait-and-retry strategies; and a new jitter formula combining exponential backoff with a very even distribution of randomly-jittered retry intervals.
+- [Polly.Contrib.AzureFunctions.CircuitBreaker](https://github.com/Polly-Contrib/Polly.Contrib.AzureFunctions.CircuitBreaker): a distributed circuit-breaker implemented in Azure Functions; consumable in Azure Functions, or from anywhere over http.
+- [Simmy](https://github.com/Polly-Contrib/Simmy): our chaos engineering project.
+- [Polly.Contrib.TimingPolicy](https://github.com/Polly-Contrib/Polly.Contrib.TimingPolicy): a starter policy to publish execution timings of any call executed through Policy.
+- [Polly.Contrib.LoggingPolicy](https://github.com/Polly-Contrib/Polly.Contrib.LoggingPolicy): a policy simply to log handled exceptions/faults, and rethrow or bubble the fault outwards.