5

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.

Improve this question
8
  • 7
    sounds like you CM department don't understand software
    – jk.
    Aug 7, 2013 at 14:05
  • 1
    Ask your CM department how they propose to build a released version of your software based only on a list of the files.
    – Blrfl
    Aug 7, 2013 at 16:24
  • 3
    @MarjanVenema: Configuration Management.
    – Blrfl
    Aug 7, 2013 at 18:45
  • 2
    @jk.: CM department understands software. They are just used to people who pack the release archives by hand, because, to be honest, they are rather widespread in the industry.
    – Jan Hudec
    Aug 8, 2013 at 13:41
  • 2
    I've seen CM unpack a perfectly automated tested installer and repack it just for job security,
    – Rob van der Veer
    Aug 8, 2013 at 19:27

4 Answers 4

Reset to default
9

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.

Improve this answer
4
  • 1
    It should be noted that configuration managers do it because they have experience. Yes, any reasonable person will use export of their version control system and that way they can't miss to pack any file, but in practice there are many teams in the wild building the release archives by hand. And than it's rather easy to miss something (my colleague processes release archives with data; the big providers have them consistent, but the smaller ones forget to ship this or that bit most of the time).
    – Jan Hudec
    Aug 8, 2013 at 13:36
  • 3
    @JanHudec: If they've got experience, they'd know the difference about automated build processes and manual procedures. If they don't trust the tools used in the build procedure, there's no point in checking the list of files provided to a tool (e.g. the files to zip here) - the output itself is just as untrustworthy. But reasonable auditors check just the manual parts.
    – MSalters
    Aug 8, 2013 at 13:53
  • @JanHudec I didn't say CM folks were wrong. It's a different mindset and intention from how programmers usually work.
    – Ross Patterson
    Aug 8, 2013 at 17:32
  • My problem is that for source code release prints, they don't even do anything with the files. They just the zip off on a network drive NEVER TO BE USED AGAIN. Why? because the programmers get an exact copy of that source from the SVN URL and revision that is already noted in a table at the top of the print.
    – pksublime
    Aug 12, 2013 at 15:24
1

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.

Improve this answer
0

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.

Improve this answer
1
  • A signature would be even better.
    – Jan Hudec
    Aug 8, 2013 at 13:27
0

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.

Improve this answer
2
  • This is kind of like what we do. The top of this document is a cross-reference table of versions, part-numbers, svn revsion, and tags. Then the build procedure or a reference to the actual procedure. Then CM wants the actual list of files, which makes our 1 page print sometimes HUNDREDS of pages long - for absolutely no reason. I'm just trying to get a feel for what other people have to do.
    – pksublime
    Aug 12, 2013 at 15:33
  • No, they want that list for a very good reason. They want to be able to audit the build process, to prove that you actually built what you thought and claimed you built. LOTS of projects have had LOTS of problems that were eventually traced back to the wrong version of something getting into the build.
    – John R. Strohm
    Sep 8, 2013 at 6:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.