DevOps Zone is brought to you in partnership with:

Lorna Jane Mitchell is a PHP developer, blogger, trainer and evangelist from Leeds in the UK. She is active with phpwomen.org and her local user group PHP North West, and writes for a variety of outlets, including her own blog at lornajane.net. She is an active member of the PHP and open source communities and contributes to the joind.in event feedback project. When she's not at her computer, Lorna enjoys yarn craft, hobby electronics, and her home renovation project. Lorna is a DZone MVB and is not an employee of DZone and has posted 67 posts at DZone. You can read more from them at their website. View Full User Profile

What Goes in Source Control?

05.01.2013
| 5178 views |
  • submit to reddit

Short answer: everything! But we need some good directory structures and source control configuration to make that a really practical answer, so this article is a quick outline of my usual advice for a good source control structure for a standard web project. The examples are for a PHP project but I'm sure you could apply this to your own language of choice, also.

Web Root

The web root of your project is never the same thing as the root of your source control folder. Typically I recommend an src directory for all code, then a subdirectory called something like public which will be your web root. The web root contains only the entry point for your application's endpoints, typically an index.php file plus any assets such as javascript, images and css that you want to serve.

Library Code

This may or may not form part of your repository. If it does, it should go in a source folder such as the src example I gave above. You may chose to bring the code in from its own repository, using source control features like submodules in git or externals in SVN. Alternatively, you may consider that the libraries are a platform dependency, place them on each server where they are needed, and either symlink to them or include them as appropriate. This is particularly useful where you have several sites building on the same shared libraries; just put them in a shared place.

Build Scripts

Using a tool like phing or ant to repeatably perform tasks within your project is an excellent practice as it can really help to make sure things are done quickly and correctly every time. Any project which takes advantage of these types of tools should include the configuration files (e.g. build.xml for phing). These should live separate from any application code, perhaps in a tools directory, or even in the root of the project.

Configuration

Configuration might be different for every platform that an application runs on, but we still need a template to start from when we work with configuration. To achieve this, create files called something like config.php.dist which contain example settings that are needed for the config (for bonus points, make these settings correct for the live platform, so that if you ever get this wrong, this platform is fastest to fix!). Every installation will need to copy the file and call it something like config.php - this should then be ignored by your source control tools so that any changes to it, on any platform, are not shared.

For systems with automated deployments, it can be useful to keep the config file(s) separately on the server, and at deploy time insert a symlink at the point that the application expects the config file to be.

Auxilliary Tools

Many applications have extra tools around them, for example I have an open source project that has a command-line tool for trying out the API, and a tool that generates sample data you can use with the application. Both of these are integral to the project and should be kept in the repository - perhaps each inside their own directory.

Database Patches

Most applications will have some way of keeping track of changes to the structure of their databases, and these are as much part of the project changes as the code is! There are tools to help with database changes, and I wrote a post about database patching strategies myself, but either way they usually result in both patch files, and files to manage the patches. Both of these should be in a database directory or similar, as part of the repo.

Tests

Tests are definitely part of your project, so keep those in the repo! This ties in nicely with the comments about phing files, which can be a great way to make it easy for people to run the various test suites that you have. Whether your project uses traditional PHPUnit testing, has functional or behavioural testing, API testing, or all of the above - check all those tests into the repository so that everyone can keep the versions up to date and run them easily.

Everything and the Kitchen Sink

Anything you need for your project belongs in the repo, it's not unusual to also have documentation as well as everything mentioned above, plus several other things I've probably forgotten - so add a comment to tell me what you store in your repo that I didn't mention?

Published at DZone with permission of Lorna Mitchell, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Craig Doremus replied on Wed, 2013/05/01 - 6:39pm

Sorry, but NOT EVERYTHING goes in source control, most notably artifacts of source code compilation (jar, exe, DLL, so files). Also, compile-time dependencies should not be in source control such as those defined in a Maven, Gradle or Ivy build. Finally (and obviously), anything that comes with the runtime environment (such as an app server) should not be in source control.

Serge Bureau replied on Thu, 2013/05/02 - 8:21am in response to: Craig Doremus

No I do agree with the author, everything should go on.

Even the app server as version might change and a customer in 5 years have an issue and you do not have this appserver anymore ?

Space is cheap so store everything that can affect your project, even dependencies.

Who says you still can produce the jar and DLL's in 5 years ?

Better safe than sorry

Lund Wolfe replied on Sun, 2013/05/05 - 6:20pm in response to: Craig Doremus

I agree.  The automated build project folder (like Maven or Ant) should be stored in source control, but not any generated artifacts.

As mentioned, database scripts and change scripts should be saved, too.

Deployment/distribution specifics should be externalized to properties files so specific deployments can easily be added/changed.

Mark Unknown replied on Mon, 2013/05/06 - 5:50pm in response to: Serge Bureau

Source Control != Control. 

"Source"  (aka code) goes in source control. (yes, things like DDL and build scripts are code).

Dependencies go in in a dependency manager.

Configuration goes in a configuration manager

"Deployables" go in a Definitive Software Library


That way you can be safe and not sorry.

Martin Feuchtwanger replied on Wed, 2013/05/08 - 11:25am

I want to understand this but your writing alone is not at all clear. Would you mind providing a simple tree diagram or two? Thanks.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.