search

pact-foundation / pact-net

.NET version of Pact. Enables consumer driven contract testing, providing a mock service and DSL for the consumer project, and interaction playback and verification for the service provider project.
https://pact.io
MIT License
845 stars 232 forks source link

Add a 'readme' to the nuget package #24

Closed sawilde closed 9 years ago

sawilde commented 10 years ago

The 'readme' should provide a getting started guide and maybe even a sample to help users quickly get to grips with PACT (.NET).

It would probably be something very similar to the readme.md or even refer to the readme.md :)

neilcampbell commented 10 years ago

Hey @sawilde. Do you see this as a physical file within the nuget package? Or would a simple link on https://www.nuget.org/packages/PactNet/ to the readme suffice?

sawilde commented 10 years ago

If you add it to the nuget package you can get it to show in visual studio when the package is first installed.

It can then provide links etc to how to get started. i.e. I didn't realize the headers were part of the verification rather than the matching.

By they way I may use your mocking tool to test the MYOB SDK as it looks much nicer then what I currently have.

From: Neil Campbellmailto:notifications@github.com Sent: ‎7/‎10/‎2014 4:31 PM To: SEEK-Jobs/pact-netmailto:pact-net@noreply.github.com Cc: Shaun Wildemailto:shaun_wilde@hotmail.com Subject: Re: [pact-net] Add a 'readme' to the nuget package (#24)

Hey @sawilde. Do you see this as a physical file within the nuget package? Or would a simple link on https://www.nuget.org/packages/PactNet/ to the readme suffice?

Reply to this email directly or view it on GitHub: https://github.com/SEEK-Jobs/pact-net/issues/24#issuecomment-58138257

neilcampbell commented 10 years ago

I'm not a massive fan of the show readme on install approach. A lot of the time, I know how a library works and I am just installing it in a new project, but yeah it certainly helps on the first install. I'm going to see what others think on this one.

With regards to the How to get started comment, I would love to hear all the things that bit you, as I know some of items are not documented in the Pact-Net readme. The one you mentioned is actually a really good example, it is document in the Pact specification project, however most users will not read that.

sawilde commented 10 years ago

The sample you gave in the readme.md was useful to getting started though I don't use xunit on my project (I did in the spike but will probably change it to nunit). Though it led me down a few wrong paths especially as it throws a 500 when you get the mock (expectation) wrong. I tried a lot of things to get it to work as I couldn't determine what was par of the expectation and what was part of the verification. By the way I think my next suggestion may be to add the doc xml file (I know people don't like code comments - but the doc xml file can be used to provide intellisense) again helps people get going quicker :)

Is there any way to see what has actually been set up so you can see what the expectation is i.e. url+query (I am assuming the query is part of the expectation) so when it goes pop you can look and go - "doh!"

sawilde commented 10 years ago

The readme can also be used to inform the user of breaking changes (hopefully none as you are awesome) and also help new users to the project when they upgrade it long after the original user has left the project that uses your package.