Merge pull request #54 from ThreeMammals/develop

merge newest

README.md

@@ -69,7 +69,7 @@ All versions can be found [here](https://www.nuget.org/packages/Ocelot/)
 
 ## Documentation
 
-Please click [here](http://ocelot.readthedocs.io/en/latest/) for the Ocleot documentation. This includes lots of information and will be helpful if you want to understand the features Ocelot currently offers.
+Please click [here](http://ocelot.readthedocs.io/en/latest/) for the Ocelot documentation. This includes lots of information and will be helpful if you want to understand the features Ocelot currently offers.
 
 ## Coming up
 

docs/building/releaseprocess.rst

@@ -1,23 +1,38 @@
 Release process
 ===============
 
-This section defines the release process for the maintainers of the project.
+Ocelot uses the following process to accept work into the NuGet packages.
-* Merge pull requests to the `release` branch.
 
-* Every commit pushed to the Origin repo will kick off the `ocelot-build <https://ci.appveyor.com/project/TomPallister/ocelot-fcfpb>`_ project in AppVeyor. This performs the same tasks as the command line build, and in addition pushes the packages to the unstable nuget feed.
+1. User creates an issue or picks up an existing issue in GitHub. 
 
-* When you're ready for a release, create a release branch. You'll probably want to update the committed `./ReleaseNotes.md` based on the contents of the equivalent file in the `./artifacts` directory.
+2. User creates a fork and branches from this (unless a member of core team, they can just create a branch on the main repo) e.g. feat/xxx, fix/xxx etc. It doesn't really matter what the xxx is. It might make sense to use the issue number and maybe a short description. I don't care as long as it has (feat, fix, refactor)/xxx :) 
 
-* When the `release` branch has built successfully in Appveyor, select the build and then Deploy to the `GitHub Release` environment. This will create a new release in GitHub.
+3. When the user is happy with their work they can create a pull request in GitHub with their changes. The user must follow the `SemVer <https://semver.org/>`_ support for this is provided by `GitVersion <https://gitversion.readthedocs.io/en/latest/>`_. So if you need to make breaking changes please make sure you use the correct commit message so GitVersion uses the correct semver tags. Do not manually tag the Ocelot repo this will break things.
 
-* In Github, navigate to the `release <https://github.com/ThreeMammals/Ocelot/releases>`_. Modify the release name and tag as desired.
+4. The Ocelot team will review the PR and if all is good merge it, else they will suggest feedback that the user will need to act on. In order to speed up getting a PR the user should think about the following.
+    - Have I covered all my changes with tests at unit and acceptance level?
+    - Have I updated any documentation that my changes may have affected?
+    - Does my feature make sense, have I checked all of Ocelot's other features to make sure it doesn't already exist?
+In order for a PR to be merged the following must have occured.
+    - All new code is covered by unit tests.
+    - All new code has at least 1 acceptance test covering the happy path.
+    - Builds for Windows, Mac and Linux must have passed.
+    - Builds for Windows, Mac and Linux must not have slowed down dramatically.
+    - The main Ocelot package must not have taken on any non MS dependencies.
 
-* When you're ready, publish the release. This will tag the commit with the specified release number.
+5. After the PR is merged the GitHub issue must be labelled as merged. The merge will trigger an alpha build on the develop branch with these changes that will get pushed to NuGet. You can import this and test it manually should you wish.
 
-* The `ocelot-release <https://ci.appveyor.com/project/TomPallister/ocelot-ayj4w>`_ project will detect the newly created tag and kick off the release process. This will download the artifacts from GitHub, and publish the packages to the stable nuget feed.
+6. When the Ocelot team is ready to create a release they will checkout a new release branch with the version from the latest develop build. So look in AppVeyor for the latest develop semver number and checkout a new branch e.g. git checkout -b release/13.1.0 and push this to the remote. Wait for it to build and then merge this branch back into master.
 
-* When you have a final stable release build, merge the `release` branch into `master` and `develop`. Deploy the master branch to github and following the full release process as described above. Don't forget to uncheck the "This is a pre-release" checkbox in GitHub before publishing.
+7. Wait for the master build to complete. When it has go to the AppVeyor UI and find the build and click the Deploy link in the top right hand corner. Select release preparation from the environment drop down and click deploy. This will send the release information to GitHub releases. 
 
-* Note - because the release builds are initiated by tagging a commit, if for some reason a release build fails in AppVeyor you'll need to delete the tag from the repo and republish the release in GitHub.
+8. Go to GitHub releases and find the version you have just released. It will look something like 13.0.0+31.build.1783. Remove +31.build.1783 (or whatever you get) from all the input fields so you are just left with 13.0.0. Untick This is a pre release and click release. This will trigger a build from AppVeyor that downloads the release artifacts from GitHub and publishes them to the stable NuGet feed. All being well you should find your new package on NuGet within 30 minutes. You might also want to manually add the issue numbers of what has been merged so people can see what changed in this release.
 
+9. The final step is to go back to GitHub and close any issues that were labelled as merged. You should see something like this in`GitHub <https://github.com/ThreeMammals/Ocelot/releases/tag/13.0.0>`_ and this in `NuGet <https://www.nuget.org/packages/Ocelot/13.0.0>`_.
 
+Notes
+-----
+
+All NuGet package builds are done with AppVeyor `here <https://ci.appveyor.com/project/TomPallister/ocelot-fcfpb>_` and all releases are done from `here <https://ci.appveyor.com/project/TomPallister/ocelot-ayj4w>_`. We also build Ocelot on Travis `here <https://travis-ci.org/ThreeMammals/Ocelot>`_ but this is only to make sure it is building on multiple OS.
+
+Only Ocelot core team members can merge PRs and create release branches. Only TomPallister can merge releases into master at the moment. This is to ensure there is a final quality gate in place. Tom is mainly looking for security issues on the final merge.

docs/features/configuration.rst

@@ -88,7 +88,7 @@ to you
                         .AddEnvironmentVariables();
                 })
 
-Ocelot will now use the environment specific configuration and fall back to ocelot.json if there isnt one.
+Ocelot will now use the environment specific configuration and fall back to ocelot.json if there isn't one.
 
 You also need to set the corresponding environment variable which is ASPNETCORE_ENVIRONMENT. More info on this can be found in the `asp.net core docs <https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments>`_.
 
@@ -131,7 +131,7 @@ You can also give Ocelot a specific path to look in for the configuration files
                 .AddEnvironmentVariables();
         })
 
-Ocelot needs the HostingEnvironment so it know's to exclude anything environment specific from the algorithm. 
+Ocelot needs the HostingEnvironment so it knows to exclude anything environment specific from the algorithm. 
 
 Store configuration in consul
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -161,7 +161,7 @@ finds your Consul agent and interacts to load and store the configuration from C
         }
     }
 
-I decided to create this feature after working on the raft consensus algorithm and finding out its super hard. Why not take advantage of the fact Consul already gives you this! 
+I decided to create this feature after working on the Raft consensus algorithm and finding out its super hard. Why not take advantage of the fact Consul already gives you this! 
 I guess it means if you want to use Ocelot to its fullest you take on Consul as a dependency for now.
 
 This feature has a 3 second ttl cache before making a new request to your local consul agent.
@@ -202,22 +202,23 @@ Use HttpHandlerOptions in ReRoute configuration to set up HttpHandler behavior:
 
 1. AllowAutoRedirect is a value that indicates whether the request should follow redirection responses. Set it true if the request should automatically 
 follow redirection responses from the Downstream resource; otherwise false. The default value is false.
+
 2. UseCookieContainer is a value that indicates whether the handler uses the CookieContainer 
 property to store server cookies and uses these cookies when sending requests. The default value is false. Please note
 that if you are using the CookieContainer Ocelot caches the HttpClient for each downstream service. This means that all requests
 to that DownstreamService will share the same cookies. `Issue 274 <https://github.com/ThreeMammals/Ocelot/issues/274>`_ was created because a user
 noticed that the cookies were being shared. I tried to think of a nice way to handle this but I think it is impossible. If you don't cache the clients
 that means each request gets a new client and therefore a new cookie container. If you clear the cookies from the cached client container you get race conditions due to inflight
-requests. This would also mean that subsequent requests dont use the cookies from the previous response! All in all not a great situation. I would avoid setting 
+requests. This would also mean that subsequent requests don't use the cookies from the previous response! All in all not a great situation. I would avoid setting 
 UseCookieContainer to true unless you have a really really good reason. Just look at your response headers and forward the cookies back with your next request! 
 
 SSL Errors
 ^^^^^^^^^^
 
-Id you want to ignore SSL warnings / errors set the following in your ReRoute config.
+If you want to ignore SSL warnings / errors set the following in your ReRoute config.
 
 .. code-block:: json
 
     "DangerousAcceptAnyServerCertificateValidator": false
 
-I don't reccomend doing this, I suggest creating your own certificate and then getting it trusted by your local / remote machine if you can.
+I don't recommend doing this, I suggest creating your own certificate and then getting it trusted by your local / remote machine if you can.

docs/features/raft.rst

@@ -3,7 +3,7 @@ Raft (EXPERIMENTAL DO NOT USE IN PRODUCTION)
 
 Ocelot has recently integrated `Rafty <https://github.com/ThreeMammals/Rafty>`_ which is an implementation of Raft that I have also been working on over the last year. This project is very experimental so please do not use this feature of Ocelot in production until I think it's OK.
 
-Raft is a distributed concensus algorythm that allows a cluster of servers (Ocelots) to maintain local state without having a centralised database for storing state (e.g. SQL Server). 
+Raft is a distributed concensus algorithm that allows a cluster of servers (Ocelots) to maintain local state without having a centralised database for storing state (e.g. SQL Server). 
 
 To get Raft support you must first install the Ocelot Rafty package.
 

docs/features/requestaggregation.rst

@@ -1,7 +1,7 @@
 Request Aggregation
 ===================
 
-Ocelot allows you to specify Aggregate ReRoutes that compose multiple normal ReRoutes and map their responses into one object. This is usual where you have 
+Ocelot allows you to specify Aggregate ReRoutes that compose multiple normal ReRoutes and map their responses into one object. This is usually where you have 
 a client that is making multiple requests to a server where it could just be one. This feature allows you to start implementing back end for a front end type 
 architecture with Ocelot.
 

docs/features/routing.rst

@@ -189,7 +189,7 @@ this sounds interesting to you.
 Query Strings
 ^^^^^^^^^^^^^
 
-Ocelot allows you to specify a querystring as part of the DownstreamPathTemplate like the example below.
+Ocelot allows you to specify a query string as part of the DownstreamPathTemplate like the example below.
 
 .. code-block:: json
 
@@ -241,5 +241,5 @@ Ocelot will also allow you to put query string parameters in the UpstreamPathTem
         }
     }
 
-In this example Ocelot will only match requests that have a matching url path and the querystring starts with unitId=something. You can have other queries after this
+In this example Ocelot will only match requests that have a matching url path and the query string starts with unitId=something. You can have other queries after this
 but you must start with the matching parameter. Also Ocelot will swap the {unitId} parameter from the query string and use it in the downstream request path. 

docs/features/servicediscovery.rst

@@ -54,7 +54,7 @@ and LeastConnection algorithm you can use. If no load balancer is specified Ocel
 
 When this is set up Ocelot will lookup the downstream host and port from the service discover provider and load balance requests across any available services.
 
-A lot of people have asked me to implement a feature where Ocelot polls consul for latest service information rather than per request. If you want to poll consul for the latest services rather than per request (default behaviour) then you need to set the following configuration.
+A lot of people have asked me to implement a feature where Ocelot polls Consul for latest service information rather than per request. If you want to poll Consul for the latest services rather than per request (default behaviour) then you need to set the following configuration.
 
 .. code-block:: json
 
@@ -67,9 +67,9 @@ A lot of people have asked me to implement a feature where Ocelot polls consul f
 
 The polling interval is in milliseconds and tells Ocelot how often to call Consul for changes in service configuration.
 
-Please note there are tradeoffs here. If you poll Consul it is possible Ocelot will not know if a service is down depending on your polling interval and you might get more errors than if you get the latest services per request. This really depends on how volitile your services are. I doubt it will matter for most people and polling may give a tiny performance improvement over calling consul per request (as sidecar agent). If you are calling a remote consul agent then polling will be a good performance improvement.
+Please note there are tradeoffs here. If you poll Consul it is possible Ocelot will not know if a service is down depending on your polling interval and you might get more errors than if you get the latest services per request. This really depends on how volatile your services are. I doubt it will matter for most people and polling may give a tiny performance improvement over calling Consul per request (as sidecar agent). If you are calling a remote Consul agent then polling will be a good performance improvement.
 
-You services need to be added to Consul something like below (c# style but hopefully this make sense)...The only important thing to note
+Your services need to be added to Consul something like below (C# style but hopefully this make sense)...The only important thing to note
 is not to add http or https to the Address field. I have been contacted before about not accepting scheme in Address and accepting scheme
 in address. After reading `this <https://www.consul.io/docs/agent/services.html>`_ I don't think the scheme should be in there.
 
@@ -108,7 +108,7 @@ If you are using ACL with Consul Ocelot supports adding the X-Consul-Token heade
         "Type": "Consul"
     }
 
-Ocelot will add this token to the consul client that it uses to make requests and that is then used for every request.
+Ocelot will add this token to the Consul client that it uses to make requests and that is then used for every request.
 
 Eureka
 ^^^^^^
@@ -160,8 +160,8 @@ Dynamic Routing
 
 This feature was requested in `issue 340 <https://github.com/ThreeMammals/Ocelot/issue/340>`_. The idea is to enable dynamic routing when using a service discovery provider (see that section of the docs for more info). In this mode Ocelot will use the first segment of the upstream path to lookup the downstream service with the service discovery provider. 
 
-An example of this would be calling ocelot with a url like https://api.mywebsite.com/product/products. Ocelot will take the first segment of 
+An example of this would be calling Ocelot with a url like https://api.mywebsite.com/product/products. Ocelot will take the first segment of 
-the path which is product and use it as a key to look up the service in consul. If consul returns a service Ocelot will request it on whatever host and port comes back from consul plus the remaining path segments in this case products thus making the downstream call http://hostfromconsul:portfromconsul/products. Ocelot will apprend any query string to the downstream url as normal.
+the path which is product and use it as a key to look up the service in Consul. If Consul returns a service Ocelot will request it on whatever host and port comes back from Consul plus the remaining path segments in this case products thus making the downstream call http://hostfromconsul:portfromconsul/products. Ocelot will apprend any query string to the downstream url as normal.
 
 In order to enable dynamic routing you need to have 0 ReRoutes in your config. At the moment you cannot mix dynamic and configuration ReRoutes. In addition to this you need to specify the Service Discovery provider details as outlined above and the downstream http/https scheme as DownstreamScheme.
 

docs/introduction/gettingstarted.rst

@@ -2,7 +2,7 @@ Getting Started
 ===============
 
 Ocelot is designed to work with .NET Core only and is currently 
-built to netstandard2.0 `this <https://docs.microsoft.com/en-us/dotnet/articles/standard/library>`_ documentation may prove helpful when working out if Ocelot would be suitable for you.
+built to netstandard2.0. `This <https://docs.microsoft.com/en-us/dotnet/articles/standard/library>`_ documentation may prove helpful when working out if Ocelot would be suitable for you.
 
 .NET Core 2.1
 ^^^^^^^^^^^^^

docs/introduction/notsupported.rst

@@ -32,7 +32,7 @@ The main reasons why I don't think Swagger makes sense is we already hand roll o
 If we want people developing against Ocelot to be able to see what routes are available then either share the ocelot.json 
 with them (This should be as easy as granting access to a repo etc) or use the Ocelot administration API so that they can query Ocelot for the configuration.
 
-In addition to this many people will configure Ocelot to proxy all traffic like /products/{everything} to there product service 
+In addition to this many people will configure Ocelot to proxy all traffic like /products/{everything} to their product service 
 and you would not be describing what is actually available if you parsed this and turned it into a Swagger path. Also Ocelot has 
 no concept of the models that the downstream services can return and linking to the above problem the same endpoint can return 
 multiple models. Ocelot does not know what models might be used in POST, PUT etc so it all gets a bit messy and finally the Swashbuckle