Versioning support without access to full SHFB projects

[fhaag]

I am trying to use the Version Builder Plug-In for indicating which parts of my library are supported by which versions of my library.

It seems that to use this plugin, one needs to point the .shfbproj file for the documentation of the current version to all .shfbproj files of previous versions to consider. These .shfbproj files, as usual, will need the compiled assembly as well as the extracted documentation Xml file.

This is where I am seeing some practical issues:

• I do not normally store .shfbproj files of previous releases. Sure, they are in the Git repository of my project, but the point of a VCS like Git is normally to have the system manage the different versions of each file, bring back specific versions upon request, and relieve me of the necessity to have all previous versions lying around side by side.
• More seriously, I consider it bad practice to store compiled assemblies in a source control repository along with the code they are compiled from. As such, relying on all compiled earlier versions of the assembly to be where my current .shfbproj file expects them does not seem practical.
• On the other hand, requiring anyone who wants to build the documentation based upon the current .shfbproj file to first check out and build all prior release versions of my library does not seem right, either.

Is there anything I am missing here? I suppose a workable middle ground could be some "digest file" for each release version that just stores a list of all types and members contained in the respective version (as that is really the only bit of information that will appear in the final documentation); this file could be checked into the VCS while keeping the amount of somewhat redundant information to a minimum ... is there any feature like this? Or is there a chance something like this might be added?

[EWSoftware]

SHFB needs something to use for comparison with the current version in order to determine what changed (reflection information files). It needs the prior versions to generate those information files. In theory, you could generate the reflection data and as long as you keep the resulting reflection information files, substitute them in place of parsing the assemblies (i.e. update the plug-in to support reflection information files in place of a project that gets built). You also need the XML comments files for the older versions too since the comments from older members would still be needed as well. As such, you'd still need to manage those plus the reflection data files for the prior releases and keep them in source control.

[cesarsouza]

What if, after each documentation compilation, SHFB could save all the necessary information for further referencing this just-compiled version in a separate directory, that could then be under version control?

The files could be named according to the documentation version string used in the configuration editor. They could even be just a dynamically created .zip containing the .dll, .xml and .shfb files that have been used in the last compilation. Yes, this could be done manually, but the point is just to make it easier to manage the information regarding the previous versions and make the process as automated as possible.

[EWSoftware]

All that should be needed is a variation or extension of the reflection data set files used to build the framework reflection data. The data set file, the results of building it (the reflection data XML files), along with the XML comments files could be stored in source control. The data set file would be referenced in lieu of a SHFB project and its outputs would be pulled in rather than building a SHFB project file.

That's the theory anyway. I just haven't had time to pursue it yet.

[EWSoftware]

Merged with #898