Add guidelines regarding dependency to Cake

[pascalberger]

While technically not required, adding a dependency in the addin nuspec file to the Cake package in the version agains which the addin was compiled could help users to see in which Cake versions the addin works.

The downside of this approach is that the Cake package will be downloaded to the addin folder in this case.

Whats considered best practice here?

[gep13]

I don't like the idea of adding the dependency when it is not required.

I have spoken with @daveaglick about the possibility of reflecting into the dll's within the nuget package to extract this information at the time of Wyam execution, to then be able to add this information to the site. Assuming that this is feasible, then the same thing could be done within this repo.

Thoughts?

[daveaglick]

I agree with @gep13, adding a dependency just for documentation purposes is asking for trouble. For example, if you're using multiple addins you'd end up downloading multiple, possibly different, versions of Cake.

What was the original goal of this proposal - to show the compatible Cake version(s) for a given addin on the Cake website? To display the Cake version as a dependency in the NuGet gallery? I guess I'd better like to understand what user experience(s) you were trying to improve.

[pascalberger]

@daveaglick Yes, the goal was to document the compatible Cake version. The drawback of documenting this on the Cake website is that it is only documented for a specific version and not for previous versions (and with the current implementation it is not even clear for which version the documentation is).

A similar case is addins depending on other addins (like eg. Cake.Prca.Issues.MsBuild requiring a specific version of the Cake.Prca addin).

[Jericho]

Regarding identifying which version of Cake a given addin works with: please note there is an automated process that audits all known addins and automatically discovers which version of Cake.Core and Cake.Common they reference. Additionally, this process also determines if addins follow other best practice such as using the cake-contrib icon, target the desired .net framework, etc. This process runs twice daily and spits out a report: https://github.com/cake-contrib/Home/blob/master/Audit.md

Hope this helps.