What documents should be added to the svn repository?

Question

I am working on a personal project, and although I have a wiki, I would like to add documentation files to the svn repository. Such files include XML (generated by monodoc), as well as UML diagrams (generated by dia).

This is a good idea, I heard / read comments about not adding binary data to the svn repository and trying to just save the code, is that correct ???

Answer 1

This is not about binary texts, but about whether it is generated or not. If you are generating these things, why not add a source of generation along with generation tools in SVN and not generated files? Then, in combination with good build scripts (also in SVN), you can always restore them again. Otherwise, you risk that the generated files are not synchronized with the source files, or people who process the generated files as “wizards” and have their own changes that are vaguely rewritable.

Answer 2

I would add all the documents, libraries, and everything else to the repository. Basically, everything that is relevant to the project, because then everyone has access to it, as well as the latest version.

Answer 3

I think it’s quite normal to store files that cannot be restored from source files to SVN. This includes dia / xml documentation and images.

Of course, it is better to prefer to store them as text where possible - so a CSV table is better than an Excel file.

Answer 4

I am not inclined to invest many binaries in subversion, except, possibly, versions of a final product. As a rule, if I can generate something on the fly, I don’t worry if it is not too long to generate them, then I just insert them there.

However, I would rather drop a copy of the latest documents (regardless of whether I can distinguish them or not easily) in svn if this makes my life easier. It is always good to be able to copy (whether it is the latest or previous version) when the boss or client says: "Do you have an xyz document from October?".

As for your specific needs, well ... only you know for sure, but disk space is cheap, and if there is value in their presence, I would do it.

Only my two cents.

Answer 5

Subversion handles binaries perfectly:

http://subversion.tigris.org/faq.html#binary-files

So, if it makes sense to have these files in your source tree, I would say check it out.

Answer 6

Add everything related to the project. Adding binary files (such as libraries) does not cause problems, but : avoid adding duplicate data, such as files that are compiled from the source.

Answer 7

svn handles binaries just fine, but I would not add inline files, but only sources. If your documentation is created from other files, do not check it if other developers create it themselves. Only if the files are hard to build will I post them in Subversion.

Answer 8

My personal rule is not to add material that you can create from another material. A good example is documentation files that can be generated from code comments.

Answer 9

If you have a documentation system that can be combined and scattered in a reasonable way, I think that the “source” for documents should be in a tree. IEtex file, not .pdf.

If you release a release that needs code and documentation editing, this documentation change will also be in SVN. When you make a release, you create binary code from the code and documentation from the documentation source.

If you transfer material from a branch, you can also back up the relevant documentation.

Answer 10

I put the data that I create and can change in SVN. For example, I put the source code, the solution, and made files and documentation in SVN. I try to avoid adding generated files, such as PDF files, created from other formats, binary files and third-party libraries. Content that I do not generate or modify, such as manuals from other suppliers, falls into a shared folder. This is all consistent with what other people say.

However, I add the generated files and binaries when I (1) release and have to save the exact released files, or (2) the files are hard to build, and I don’t want other developers with the build process. I sometimes add third-party libraries for convenience so that new developers do not have to find, download and install them - this is very useful for me, since many of my development machines do not have an Internet connection.