what to save in git (or any other revision control system)?

Question

I'll take Drupal as the exmple for my first question. We have a drupal instance with a custom theme and many downloaded modules. We have a server used as the source code repo. The current workflow of work on the dev instance of drupal then migrate the changes over to test. Once clients test it out and like the changes move them to production. - Should I place the whole drupal dir in git? or theme+plugins? or just the theme? One advantage of placing the whole instance is i can easily clone the changes on prod and it would look identical to dev and test.

Second question is when we do local customization to the product's core code (let's take DSpace as an example). We get version 1.6 and do local changes and keep them in our repo. Then when they release the version 1.7 I have to get that and merge my local changes to that. How do I get 1.7? Can i get in to a branch?

What the best practice in these situations.

Thanks.

PS - I know about git ignore and how to do it technically. What I'm looking for is advice on best practices.

Answer 1

In order of importance:

1. Put everything into Git which is necessary to build the project (i.e. including all dependencies which the build process doesn't download by itself)
2. Put everything into Git to run the project on a developer machine
3. All the generated files (often useful for finding sudden bugs - a.k.a "But I didn't change anything!"). These are nice to have but can be a nuisance since they change often.
4. All the dependencies (so you can easily recreate an old build)

I usually don't put the production version into Git; instead I have a script which creates a production site out of the project plus an upload script to deploy this site. That way, I can give the new production version a local run. And the upload script has a step "backup old files" so I can restore the old production site in a few minutes (well, unless some bug has corrupted the database).

[EDIT] A lot of people disagree with points #3 and #4.

First of all, (as I already said above), this is an ordered list. So the first two points are much more important than the rest.

That said, it still makes a lot of sense to version generated files. Common cases are IDE project settings and output of code generators.

Why version them when it's so simple to recreate them? There are several reasons:

1. Hard disk space is cheap. If this can help you find a bug in one hour less, that equals to about $100 which is about 2TB of disk space.

2. IDE project files contain compiler settings and other very important configuration. If you don't always have them under version control, you will eventually have this situation: The files will be in the ignore list of your DVCS. You find a problem (like an important warning which should be active). You activate the warning. You forget to add the changed file to version control.

   Or: You're part of a team. After one month, everyone in the team uses different options to build their projects. Builds break because something is configured as a warning in your IDE but it's an error for someone else.

3. Code generated by some tool surely shouldn't be versioned? Isn't it enough to version the config files of the code generator?

   Maybe. The question is again: Will you ever have to find a bug in this code? And even if not: When the files are under version control, it will be very easy to see what the change of a config option means. You just change the option, run the code generator and let your version tool show you what has changed. Sure, you could do something similar manually but why waste so much effort for something that can be had for free?

4. Most importantly, it will cause "spurious merge conflicts". Many people think this is a problem but it's not. In fact, you will want to see these problems because it means that your build is unstable:

   1. Your VCS says a file has changed when it shouldn't; that's not a bug, it's a boon. Without version control, this change would have happened anyway but you wouldn't have noticed it. When was the last time ignorance was better than knowledge?
   2. You have merge conflicts in one file over and over again. This is an indicator that your build or project setup needs some love. Again: Solving merge conflicts is a pain. But it is really better that every developer gets their own version of the file without noticing?