Which elements must be under the version control?

Thursday, October 25, 2007 5 Comments

After a few conversations with some of our customers and different users of SCM systems, I have realized that in some cases it is not very clear which elements must be added under the version control. I will try to explain it in this post.

The usual thing would be to always include under the version control every resource which is part of a project, except those resulting from the compilation or generation system.

For instance, the source code will be surely included under the version control. But, what happens with the rest of resources belonging to the project? Images, database scripts, compilation files (make, Ant...), binaries, documentation...

It may be more interesting to concentrate on the resources that should NOT be included under the version control.

Every binary file resulting from a compilation or generation (reports, etc...) should never be included under the source control. The environment should be ready to compile and generate automatically whatever is needed (Ant, NAnt, MSBuild, make,...)

Development environments very often do this for us. For example, Visual Studio, through the integration with the source control, is able to determine which elements are included under the source control and which of them are not.

In the example, Visual Studio project, folders bin and obj are not included under the source code.

Within other development environments such as Eclipse, NetBeans, etc..., exclude or ignore patterns can be defined. The environment allows defining items which will not be taken into account when adding the solution under the source control:

Finally, when we are not working with any development environment we will have to do this task "manually" (we can create a script using the operative system metacharacters *, ?, to "automatically" add elements under the version control).

5 comments:

  1. Hi there,

    Just wanted to say that you've got a great series of blogs going here. I've been reading them from the beginning and they've always been entertaining, informative and regular. Keep up the good work!

    I've a question for you. A while ago you posted a blog that explained that you create a new source control stream for every bugfix, or feature that you work on. My question is, do those streams also include all of the source control artifacts as well as the source code? For example, do those stream include things like Installer packages, database scripts, help documentation etc?, or are they just source code only?

    If they don't, how are you managing these other things? For example, if a bug fix requires an alteration to an installation package (Installshield etc), how is this managed?

    I am trying to put together a source control methodology and I am starting to lean toward putting everything into one stream and the whole thing gets created for each fix.

    Many thanks,

    Rod

    ReplyDelete
  2. Hi Rod,

    Well, this is a pretty good question actually.

    I'd put everything under source control, including installer packages, database scripts and the like.

    For database scripts the scenario is pretty simple: they'll be handled as regular text files, so you'll even have merge capabilities available.

    For binary-based assets things get a bit more complicated. I'll give you an example:

    - We have two repositories (well, in fact our own source code is split into at least 5 reps, which wouldn't be a regular practice for such a project, but it is a good *eat your owns dog food technique* for us) one of them containing test code. The binaries generated for testing are actually copied into the "src" repos to test. Well, if two of us have to make a bug fix and generate a test case to check it is correct, we'll both generate the tests and replace the test binaries in our branches (streams).

    - Later on the integrator will notice there's a problem with the binaries, because Plastic will ask him to choose between one library and the other. He'll take one of them, and later on recompile the test binaries and replace them...

    The problem here is that merging binaries (executables) is not possible.

    For installer packages it could be simpler when you're dealing with the installer configuration itself: most of the modern tools treat them as XML or some sort of text files. So merging would be possible. The resulting installers wouldn't normally be included inside the repository (ok, they could be stored in some sort of stating area to be used by third parties, but this is a whole story itself) so you won't be in trouble merging them.

    So, in short: yes, use your fix-branches to modify not only source code but also installer package generation, database scripts, help documentation source, and so on.

    If any of the assets shouldn't be modified in parallel (it can happen for some file formats), then Plastic will enable to do so using the selector. If this is the case just let me know and we talk about it further.


    Thanks!

    pablo

    ReplyDelete
  3. Hi Pablo. Many thanks for your answer. This all makes good sense. Our source control methodology is a work-in-progress, so it's good to pick up more tips along the way.

    Keep up the great blogs

    Best regards,

    Rod

    ReplyDelete
  4. Hi,

    This is a very great system you guys built! Documentation and resources are very helpful too! I enjoy reading this. Great job!

    I have a note why sometimes you may need to keep compiled and tested binaries along with the source code.

    We are using Delphi. Delphi compiler has such a feature to produce a random junk in some areas of your binary file. I don't want to touch here why it happens, it's a different topic. Whenever you compile the same source code you end up with different binaries. This would be a minor issue if it was not related to stability of your final result. There are type of low-level bugs which may try to use those junk areas. In some cases it may be harmless, in others it may completely blow up entire process. It depends on what type of random junk you've got in there.

    In other words, it might be a need to keep binaries along with source code (for history), instead of relaying on compiling.

    With respect,

    Aleksey

    ReplyDelete
  5. Excellent point!

    Of course we DO include binaries on source control too. The point we wanted to explain is that "generally speaking" you put the sources and get the binaries out of them...

    But of course your point is sound and clear!!!


    Thanks for the comments.

    ReplyDelete