Is there a best practice for how to document the source code you’re releasing?
Currently, we have a table of the versions of the software, what SVN tag it’s labeled as, what SVN rev that tag was created at and the SVN URL.
Then, our CM (Configuration Management) department wants us to include a file listing of all the source files we’re including for the .zip that we provide them which is just a zip of the tag we’re releasing.
I’m more fishing for ideas to update our print template, hopefully with good arguments to remove the file listing.
8
Configuration Management (CM) folks don’t think like programmers. They think more like auditors. The reason they want a list of the files is because they want to verify that they got them all. Yes, this seems silly to a programmer, but it seems natural to someone who doesn’t trust a single source of information. Ideally, your list of files would not merely be an svn status -v or an ls -lR, but a human-mediated list of the specific files necessary to build your system and which you intend to provide. Thus, for example, you would not list or provide the generated source files from a code generator that runs during the build process, even if they happen to be in your workspace at the time you build the ZIP file.
4
I’m not sure about what you’re exactly asking for. If you need a zip of the files at a certain release/tag, here’s what git offers:
git archive --output myzip.tar.gz mytag
Maybe there’s a similar concept for `svn’, too.
The part that I add is a hash. That’s a much shorter string, and yet it depend on every character in the compiled source.
1
A lot depends on your definition of “release”.
In the military-industrial complex, a release is described by a Version Description Document. It contains, among other things, a complete list of all files that go into the release, with the exact version number for each file (from whatever CM system), a complete list of all tools needed to recreate the release from the distribution media, and the procedures for (a) recreating the released software using exactly those tools and the distribution media and (b) loading the recreated release onto the hardware. Ideally, those procedures should be “Heathkit manuals”: step-by-step procedures, that have been carefully tested by people who do NOT normally do those things, but I’ve seen a lot of sloppy work in this department (and at least once been told to sit down and shut up when I pointed out a VDD procedure that was incorrect).
I’m sure I’ve overlooked something. Google “Version Description Document” for more information.
2