12.2. Checking In Code As soon as code is committed to a repository, it becomes available for other developers to check out and use (barring permission restrictions). If the code is committed on the trunk, or a public branch, it not only becomes available, but it enters the HEAD revision and any developers performing an update will find those changes merged into their own working copies. This means that if a developer commits changes that break the source on a trunk or branch in a way that blocks other developers from continuing with their work, there will be a lot of wasted labor as developers scramble to figure out why their working copies no longer work and either fix the problems or roll back all or part of their working copy to previous revisions in order to be able to continue their own work. To avoid time-wasting problems from prematurely committed code, it is important to have a set of policies that define when developers should be performing commits. There's nothing radical here, and most of the policy suggestions I make are commonsense etiquette. They're also mostly universal. They may not always be appropriate for every project, but I would think hard before throwing any of them out. Never commit code that hasn't been compiled. If it doesn't compile for you, it probably won't compile for anyone else either. By committing a revision that doesn't even compile, you are costing at least a few wasted minutes for most of the other developers on the project, and possibly more if the reason for the failed compile isn't immediately obvious (for example, if other developers think the problem may be caused by the interaction of their changes and yours). You will also introduce a broken revision that can cause confusion (and headaches) in the future. Avoid committing untested code. For essentially the same reasons that you should never commit source code that can't be compiled, you should also avoid committing code that hasn't been thoroughly tested. Unfortunately, it is hard to make this as hard and fast as the compile rule. Sometimes, it just isn't possible to test code before you commit it. For instance, you may not have the environment necessary to test the application on your development machine, or you might require modifications from another developer before thorough testing can take place, or in some cases it just might not be your job to do thorough testing before you commit. If the committed code is destined for a QA testing team, they may be the ones doing the thorough testing. You also may sometimes make changes to the source that are so trivial that there is little reason to actually test. In most cases, you should test anyway, but if testing is hard and the change is truly trivial, it may be acceptable. Always update and test before committing. If you have been working on a modification for a while, and are finally ready for a commit, it is possible (probable, even) that other developers have committed their own modifications in the meantime. So, even if you have thoroughly tested your modifications in your own working copy, it is important to do an update of all the project components that may be affected by your change and test against the updated version. Use a diff to check exactly what will be committed. It's easy to forget to remove one-off debugging code, or to make a minor change that should be committed as a separate revision and then forget you made it. By actually looking at the changes you will be committing before you run the actual commit, you can make a sanity check to make sure you're committing what you think you're committing. To perform the diff, run svn diff with no options on the working copy directory (or file) that will be committed. Try to commit only one distinct modification per commit. When you commit a modification to the repository, it should be a single atomic modification. That way, it is easy to roll back just that modification if you need to at a later point. For instance, if you modify a function that adds up a series of numbers, and at the same time add in a dialog box for confirming database modifications, you shouldn't commit both to the same revision. If at all possible, commit one modification and then the other (which is easy if they're in completely different filesjust commit one set of files and then the other). The best way to avoid accidentally committing two modifications, though, is to commit frequently. Don't commit incomplete changes on a common branch. There is wisdom in committing atomic modifications, but be careful with committing modifications that are too small. If you commit incomplete features, you may find that rolling back those changes is more difficult (because there are more revisions involved). You will also likely find that commits that are too small will tend to break the branch, because they are not complete features in and of themselves. If you are going to be making a lot of changes that would be well-served by multiple commits, but aren't logically multiple feature modifications, you may be well-served by creating a branch for making those changes. That way, you can do a lot of little commits, and then combine them all into a single merge that puts those changes into the main trunk (or another branch) in a single step.
|
