Merge pull request #225 from reisenberger/v505doco-NoOpPolicy

CHANGELOG.md

@@ -3,6 +3,7 @@
 - Bug fix: Prevent duplicate raising of the onBreak delegate, if executions started when a circuit was closed, return faults when a circuit has already opened.
 - Optimisation: Optimise hotpaths for Circuit-Breaker, Retry and Fallback policies.
 - Minor behavioural change: For a circuit which has not handled any faults since initialisation or last reset, make `LastException` property return null rather than a fake exception.
+- Add NoOpPolicy: NoOpPolicy executes delegates without intervention; for eg stubbing out Polly in unit testing.
 
 ## 5.0.4 pre
 - Fix Microsoft.Bcl and Nito.AsyncEx dependencies for Polly.Net40Async. 

README.md

@@ -44,6 +44,8 @@ Polly offers multiple resilience policies:
 
 # Usage – fault-handling policies
 
+Fault-handling policies handle specific exceptions thrown by, or results returned by, the delegates you execute through the policy.
+
 ## Step 1 : Specify the  exceptions/faults you want the policy to handle 
 
 ### (for fault-handling policies:  Retry family, CircuitBreaker family and Fallback)
@@ -455,6 +457,8 @@ Policy
 
 # Usage – general resilience policies
 
+The general resilience policies add resilience strategies that are not explicitly centred around handling faults which delegates may throw or return.
+
 ## Step 1 : Configure
 
 ### Timeout
@@ -567,6 +571,17 @@ Reputation reps = Policy
 
 For more detail see: [PolicyWrap documentation](https://github.com/App-vNext/Polly/wiki/PolicyWrap) on wiki.
 
+### NoOp
+
+```csharp
+// Define a policy which will simply cause delegates passed for execution to be executed 'as is'.
+// This is useful for stubbing-out Polly in unit tests, 
+// or in application situations where your code architecture might expect a policy
+// but you simply want to pass the execution through without policy intervention.
+NoOpPolicy noOp = Policy.NoOp();
+```
+For more detail see: [NoOp documentation](https://github.com/App-vNext/Polly/wiki/NoOp) on wiki.
+
 ## Step 2 : Execute the policy.
 
 As for fault-handling policies [above](#step-3--execute-the-policy).
@@ -760,6 +775,10 @@ For `CircuitBreakerPolicy<TResult>` policies:
 * A circuit broken due to an exception throws a `BrokenCircuitException` with `InnerException` set to the exception which triggered the break (as previously).
 * A circuit broken due to handling a result throws a `BrokenCircuitException<TResult>` with the `Result` property set to the result which caused the circuit to break.
 
+# Release notes
+
+For details of changes by release see the [change log](https://github.com/App-vNext/Polly/blob/master/CHANGELOG.md).  We also tag relevant Pull Requests and Issues with [milestones](https://github.com/App-vNext/Polly/milestones), which match to nuget package release numbers.
+
 # 3rd Party Libraries
 
 * [Fluent Assertions](https://github.com/dennisdoomen/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)
@@ -801,6 +820,7 @@ For `CircuitBreakerPolicy<TResult>` policies:
 * [@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.
 
 
 # Sample Projects

src/Polly.Net40Async.nuspec

@@ -20,6 +20,7 @@
      - Bug fix: Prevent request stampede during half-open state of CircuitBreaker and AdvancedCircuitBreaker.  Enforce only one new trial call per break duration, during half-open state.
      - Bug fix: Prevent duplicate raising of the onBreak delegate, if executions started when a circuit was closed, return faults when a circuit has already opened.
      - Optimisation: Optimise hotpaths for Circuit-Breaker, Retry and Fallback policies.
+     - Add NoOpPolicy: NoOpPolicy executes delegates without intervention; for eg stubbing out Polly in unit testing.
 
      5.0.4 pre
      ---------------------

src/Polly.SharedSpecs/Helpers/PolicyExtensionsAsync.cs

@@ -80,15 +80,13 @@ public class ExceptionAndOrCancellationScenario
             }, cancellationToken);
         }
 
-        public static Func<Task> Awaiting(this Policy policy, Func<Policy, Task> action)
+#if PORTABLE
+        // Omitted the Portable versions of FluentAssertions.  Hence re-included here for #PORTABLE only.
+        public static Func<Task> Awaiting<T>(this T subject, Func<T, Task> action)
         {
-            return (Func<Task>)(() => action(policy));
+            return (Func<Task>)(() => action(subject));
         }
-
-        public static Func<Task<TResult>> Awaiting<TResult>(this Policy<TResult> policy, Func<Policy<TResult>, Task<TResult>> action)
-        {
-            return (Func<Task<TResult>>)(() => action(policy));
-        }
-
+#endif
+
     }
 }

src/Polly.SharedSpecs/NoOp/NoOpAsyncSpecs.cs

@@ -14,7 +14,7 @@ namespace Polly.Specs.NoOp
     public class NoOpAsyncSpecs
     {
         [Fact]
-        public void Should_not_throw_when_executing()
+        public void Should_execute_user_delegate()
         {
             NoOpPolicy policy = Policy.NoOpAsync();
             bool executed = false;
@@ -26,7 +26,7 @@ public void Should_not_throw_when_executing()
         }
 
         [Fact]
-        public void Should_execute_if_cancellationtoken_cancelled_before_delegate_reached()
+        public void Should_execute_user_delegate_without_adding_extra_cancellation_behaviour()
         {
             var policy = Policy.NoOpAsync();
 

src/Polly.SharedSpecs/NoOp/NoOpSpecs.cs

@@ -13,7 +13,7 @@ namespace Polly.Specs.NoOp
     public class NoOpSpecs
     {
         [Fact]
-        public void Should_not_throw_when_executing()
+        public void Should_execute_user_delegate()
         {
             NoOpPolicy policy = Policy.NoOp();
             bool executed = false;
@@ -25,7 +25,7 @@ public void Should_not_throw_when_executing()
         }
 
         [Fact]
-        public void Should_execute_if_cancellationtoken_cancelled_before_delegate_reached()
+        public void Should_execute_user_delegate_without_adding_extra_cancellation_behaviour()
         {
             NoOpPolicy policy = Policy.NoOp();
             bool executed = false;

src/Polly.SharedSpecs/NoOp/NoOpTResultAsyncSpecs.cs

@@ -14,7 +14,7 @@ namespace Polly.Specs.NoOp
     public class NoOpTResultAsyncSpecs
     {
         [Fact]
-        public void Should_not_throw_when_executing()
+        public void Should_execute_user_delegate()
         {
             NoOpPolicy<int?> policy = Policy.NoOpAsync<int?>();
             int? result = null;
@@ -27,7 +27,7 @@ public void Should_not_throw_when_executing()
         }
 
         [Fact]
-        public void Should_execute_if_cancellationtoken_cancelled_before_delegate_reached()
+        public void Should_execute_user_delegate_without_adding_extra_cancellation_behaviour()
         {
             NoOpPolicy<int?> policy = Policy.NoOpAsync<int?>();
             int? result = null;

src/Polly.SharedSpecs/NoOp/NoOpTResultSpecs.cs

@@ -14,7 +14,7 @@ namespace Polly.Specs.NoOp
     public class NoOpTResultSpecs
     {
         [Fact]
-        public void Should_not_throw_when_executing()
+        public void Should_execute_user_delegate()
         {
             NoOpPolicy<int> policy = Policy.NoOp<int>();
             int? result = null;
@@ -27,7 +27,7 @@ public void Should_not_throw_when_executing()
         }
 
         [Fact]
-        public void Should_execute_if_cancellationtoken_cancelled_before_delegate_reached()
+        public void Should_execute_user_delegate_without_adding_extra_cancellation_behaviour()
         {
             NoOpPolicy<int> policy = Policy.NoOp<int>();
             int? result = null;

src/Polly.nuspec

@@ -20,6 +20,7 @@
      - Bug fix: Prevent request stampede during half-open state of CircuitBreaker and AdvancedCircuitBreaker.  Enforce only one new trial call per break duration, during half-open state.
      - Bug fix: Prevent duplicate raising of the onBreak delegate, if executions started when a circuit was closed, return faults when a circuit has already opened.
      - Optimisation: Optimise hotpaths for Circuit-Breaker, Retry and Fallback policies.
+     - Add NoOpPolicy: NoOpPolicy executes delegates without intervention; for eg stubbing out Polly in unit testing.
 
      5.0.4 pre
      ---------------------