We are working on a single project, and also committing code at the end of day on SVN so that can get all update project. But issues is very often our code getting errors while committing code and projects get empty if someone get update at that time. So my question is are there any set of rules which we've to follow on committing so that every one go on straight path and no one get in trouble and save a lot time from these errors.
Thanks in advance. Cheers
Search Google, something similar to "source control best practices".
Top result has several tips. Sounds like the biggest problem you're facing is integrating with others' changes. Perhaps look into the following sections:
Incorporate others' changes frequently
Share your changes frequently
Coordinate with your co-workers
Investigate why you get errors. Blind application of rules is not good.
For example:
person A committed a code producing compilation error
why?
he finished his task, but hasn't checked build before committing to the trunk
why?
the entire build it too slow
solution: speed-up build, set up continuous build system which will check every commit and notify developers about problems as soon as possible
Another example:
person B committed a code which breaks the build
why?
he wanted to store his changes, but the task is not finished
solution: advice him to create a branch, when the task is finished it can be merged to the trunk (if branch lives for long time, merge changes from trunk to it periodically, then the merge will not be a problem)
There possible other scenarios. With more details you will be able to ask more precise question on StackOverflow and get better answers.
In case of use of SVN co-ordination is must between the team.
Make sure whenever you commit the code you have a idea about what are you committing.
The golden rule is "One developer One class".
If at all two different developers are working on same class. Ask them to maintain a document on what changes they have made. And, most important to mark a comments in a class it self.
There are some important things which need to be followed while committing the code. Whenever you see a conflict in your local files and server files. Make sure you go through every conflict and select the appropriate action.
Understand one important thing, whenever SVN is used one persons mistake can affect everyone.
Whenever possible, don't edit the same line of code as someone else
Leave meaningful comments on your commit messages
Comment your code
Make sure that all the code you commit compiles and runs as it should
Commit when appropriate ie: are passing off part of your code to be used by others or are done working on a feature
Make sure to communicate with other team members
If you find code that you don't know what it does, ask the author
If you're making major changes that will take a while to implement, use a branch and then merge it back in
Related
I struggled asking that question but here it is.
I am using source control since several years for multiple projects using different systems (svn, hg, git) and I learned how to improve my messages by following guidelines etc.
But as far as I can remember I never ever had a look at them afterwards.
So ... how do you profit from your own commit messages? When I need to go back because I smashed something and need a fresh start, I usually just go back to the latest "node" (where I started or merged a branch). Do I write those messages just for people monitoring the project who are curious what is going on?
Regards
You write them as an aid to your future self, and others on the team. To give you some background of when I have found them useful:
I used to work on a project where commit messages were invaluable - on more than one occasion I used them to track down code that was years old. On that project our bug tracking system was also integrated with our VCS (ClearCase). So when you checked in a change, it would record the bug number in the commit comments. This was very helpful to allow you to trace back exactly what was changed and why.
So to sum it up, although commit messages may seem pointless if you are just starting out (especially if you are the only one working on the project), they become invaluable once you have a successful product that is supported in production by multiple developers.
Update
Another useful feature of commit messages is that they require you to review and summarize the changes you just made. Even if I remember what I have changed, I will often do a quick diff of a file before checking it in. I will briefly read it all over again to make sure there are no typo's, that I changed everything I meant to, etc. This is a simple way to review your code for those small little bugs that would otherwise find their way into your code. Anyway, after doing this I have a clear picture of what changed, so I use this to write a concise summary of the change when checking in the file. This is a simple habit that helps increase code quality with little effort on your part.
"Send me a list of the things you did in the past two weeks" - Boss
Your messages are more for other users than yourself. Although I make sure to place good commit messages even on personal repos as well. Helps when you get sidetracked on a project and visit it months down the line to get a handle of the recent work done on a project.
One thing I've found is that the commit messages are a good way to keep myself from not committing often enough. If I can't put the changes into a short commit message I probably should have committed the changes earlier.
In the best case, a commit is bound to a work item in a feature/bug tracker. That way you will be able to easily see which feature/bug has been implemented/fixed. This is not only useful to know if a certain revision contains a feature or bug fix but also to easily create a release note.
What would be the point of a commit without a note to tell you what it is? It's like asking 'Why do books have titles on the sides?', or perhaps 'Why do books have indexes and page numbers?'. It seems to me that a source control log that didn't have a description for each change wouldn't be very useful.
Reasons you may need to refer to the commit message include
A bug has surfaced and you want to find when that part of the code was changed last
You decide to undo some changes and need to decide which revision to revert to
For either of these possibilities, without good commit messages, you would be left looking through the diffs for every single commit until you found what you were looking for in the code.
I've been working on an Xcode (iPhone) project with three different persons. We have the project on a Subversion repository, but we still don't completely understand some aspects of the Subversion + Xcode methodology:
1) Each time someone does a commit on a single file, it may appear or not in the project of the other developers. Even though the same person that creates the new files, it adds those files to the Repository and then it commits on those files. Why does that happens? Any suggestions?
2) Each person that is involved on the project can't do a "Commit entire project" without causing a considerable headache to the rest of the developers... any idea how this should be done?.
The working methodology that we are trying to implement is that only one developer (generally the leader of the project) can Commit the entire project but he must inform the rest of the team, so everybody can be prepared to receive a message asking him to discard his changes and read the new files from the repository.
I need suggestions or advice on how to handle a project with multiple developers using subversion.
We have read the Subversion handbook, and many other messages on StackOverflow but I still can't find any useful advice.
Thanks for any tip!
The reason the other guys are not seeing the changes is that they are not informed until they attempt to do an "update", "commit" or "diff" against the repository. SVN is a "pull" system, the repository doesn't inform the clients of anything without a command from them.
Communication is the key. If your developers are generally aware of what is going on in the project, or at least in their corner of the project if it's a large one, they'll minimize the risk of committing code that will upset the project.
Insisting that only one developer is allowed to commit to the repository is overkill IMHO and quite contrary to the whole idea of using version control. You might as well just have a single folder that only that developer can write to using a diffing tool each time.
Make sure your guys do an "Update", Compile, Test cycle before they "Commit". That way they are less likely to commit code that will break the build. If they're just a little careful, you'll all get the hang of it real quick, there really isn't that much to worry about. Good luck.
You are saying "The working methodology that we are trying to implement is that only one developer (generally the leader of the project) can Commit the entire project but he must inform the rest of the team, so everybody can be prepared to receive a message asking him to discard his changes and read the new files from the repository." Why is that needed? Are the other devs not able to checkin or not good enough to checkin code ? Sorry to say that in a drastic way: That's bull-shit. Every developer should be able to commit. If you like to separate the developers from each other you should use branches for this. And as already mentioned the communication is done by svn update/svn status -u etc.
I am starting to get a reputation at work as the "guy who breaks the builds".
The problem is not that I am writing dodgy code, but when it comes to checking my fixes back into source control, it all goes wrong.
I am regularly doing stupid things like :
forgetting to add new files
accidentally checking in code for a half fixed bug along with another bug fix
forgetting to save the files in VS before checking them in
I need to develop some habits / tools to stop this.
What do you regularly do to ensure the code you check in is correct and is what needs to go in?
Edit
I forgot to mention that things can get pretty chaotic in this place. I quite often have two or three things that Im working on in the same code base at any one time. When I check in I will only really want to check in one of those things.
A few suggestions:
try work on one issue at a time. It's easy to make unrelated changes to the codebase that then end up being committed as one big chunk with a poor log message. Git is excels here since you can so easily move switch branches, and stash and cherry pick changes.
run the status command before a commit to see which files you've touched and if you've created new files that need to be added to version control.
run the diff command to see what you've actually changed. Often times you find that you've left in some debug logging that should be taken out or made some unnecessary change that is just cluttering up the diff. Try to make your diffs as small and clean as possible.
make sure your working copy builds with your changes in it
update before checking in and make sure that your working copy builds with other peoples changes in it
run what ever smoke test suite you might have to make sure that your changes work correctly
make small and frequent commits. It's a lot easier to figure out what has broken the build when the breaking commit is small.
Other things that the team can do is setup a continuous integration server like David M suggested so that the broken build is discovered as soon as possibly and automatically.
I usually always do a Get Latest before, then build. If build is good then I check in my code.
Here is what I have been doing. I have used ClearCase and CVS in the past for source control, and most recently I have been using Subversion and Visual Studio 2008 as my IDE.
Make my code changes and build on the local machine.
Make sure they do, in fact, fix the bug in question.
Run an SVN update on the local machine and repeat steps 1 and 2.
Run through the automated unit tests to verify that they pass.
If an automated smoke test is available, which automatically tests a lot of the system's capabilities, run it. Verify that the results are correct.
Then go to the build machine and run the build script.
If the project's configuration has changed, this could definitely break a build. Perform an SVN update on the build machine, whether the build script does that or not. Open the build machine's copy of the IDE, and do a complete rebuild. This will show you whether the build box has any problems that you have taken care of on your machine but not on the build box.
The suggestions to keep separate branches for each issue are also very good, if you can keep track of all of the issues you are working on.
First, use multiple working copies (a.k.a sandboxes) - one per issue. So, if you've been working on some complex feature for a while, and you need to deal with a quick bug fix on the same project, check out a new clean working copy and do the bug fix there. With independent working copies for each issue there is no confusion about which changes to commit from the working copy to the reposistory.
Second, before committing changes, always perform the following three steps:
Buld the software.
Run a smoke test (does it start and run without crashing).
Inspect the changes you're checking in by diffing your changes against the baseline.
These should be repeated after any merge operations (e.g. after an SVN update).
At my workplace, the safety net for this is peer review. That is, get someone else to build, run, and reproduce your solution on their machine, on their view.
I cannot recommend this enough. It has caught so many omissions, would-be problems, and other accidental pieces of junk to make it a valuable part of the process. Not to mention that the mere knowledge that you have to place your work in front of someone else before having it go on to the main branch means that you raise your own quality standards.
In the past I have used branching in Clear Case to help with this issue. The process I used is below. I've never used SorceDepot so I do not know how this can be adapted to work with it.
Create a branch for the bug fix
Code all changes on the branch
Code Review
Merge to stable branch in a different view (the different view is important)
BEFORE checking in: compile, test, and run
Check in code to stable branch
By creating the branch and then merging the changes to a different view (I use Merge Manager to do the merge) any files that were not included or checked in immediately cause issues. This way everything gets tested as it will be when checked in on the stable branch.
The best thing to avoid your problems, is to use hooks, that are provided in most SCMs (they are for sure in SVN and Mercurial, and I believe they must be in other advanced SCMs). Attach unit tests to the hook and make it run every time someone checks code in - exactly before it is checked in. This way you will achieve two things:
code in SCM repo will always pass the tests,
you won't make most simple mistakes, because they should be easily detectable, if you have decent test suite.
I like having Tortoise plugins for Windows Explorer. The file icons are all badged with committed, modified or not added icons making it very easy to see what status the files are in. I also enable the meta data for Modified so I can sort changed files in the list (Details) view, where they bubble to the top so I can see them.
I bet there is a Tortoise* plugin for your SCM, I saw one for Mercurial and SVN (and CVS, ugh). I really wish Mac OS X's Finder would accept plugins like Tortoise, its so much easier than having to pop open a dedicated app most of the time.
Get someone else to go through "every" change "before" you check in the code.
What template do you use for comments on code commit?
One example of a template is:
(change 1): (source file 1.1, 1.2): (details of change made), (why)
(change 2): (source file 2.1): (details of change made), (why)
Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
Given these ideas, an example commit comment for me would be something like
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
I prefix each paragraph with + - * or !
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
If you use a bug tracking system, include relevant ticket numbers.
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
I try to follow the same rule as for code comments:
Explain the WHY, not the HOW.
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
I try to keep my fixes in separate check-ins.
I don't use an actual template, but a mental one, and it's like this.
Issue - dev level summary of
issue.
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
Here's what I've seen used successfully:
Reference to bug number or feature ID
Brief description of the change. What was changed.
Code reviewer (to ensure you have one) unless handled by the checkin system.
Name of tester or description of which tests were run (if late in the process and you are being extra careful)
I use the simple technique described by Chaosben on the JEDI Windows API blog.
In order to get a fast view on the
changes made to a repository, we
suggest to write brief concise
comments starting each line with one
of these chars:
+ if you added a feature/function/…
- if you removed a feature/function/bug/…
# if you changed something
Doing it this way, other developers may find the desired revision much better.
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
I think that commit message conventions expected and used by git makes much sense:
The first line of commit message should be a short description
If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
In next paragraph or paragraphs describe the change, explaining why's and how's
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change
There is a lot of conversation about commenting code, but how about commenting on check-ins?
I found this blog post:
http://redbitbluebit.com/subversion-check-in-comment-great-practices/
As the guy who is putting together the release notes, I am looking for ways to make that job easier.
Currently we defined our own scheme with <Begin_Doc>...<End_Doc> for anything that should be published to our software customers. But even for the internal stuff, I'd like to know the "why" for every change.
Every feature has a ticket/issue/bugreport/task/whatever-you-call-it, and the ticket number is always referenced in the check-in comment. This gives context.
I would advocate NOT using/overloading your version control system for this. I would suggest the issue tracking software as a better fit.
For one, it does not seem appropriate to have developers add all the context and duplicated information in a commit message that is already in a requirements doc or issue/defect system.
You can use a tool to gather the relevant fixes/issue numbers that are in the commit comments and then go collect those from your other repository, but I think it is a mistake to basically make your revision tool an external facing thing.
You need to define what the Source/version repository/SVN is - is it for managing your source files, or is it also for writing release note. I think it should not be overloaded.
We try to keep it simple: write one sentence describing the change that you are committing. If a developer needs two or more sentences to describe the commit, then perhaps the commit is two unrelated pieces of work. When commits like this end up in version control, then it is difficult to revert fixes in isolation.
Another piece of information that we like to include in our commit comment is the defect / feature number that the commit fixes / implements. Not all work that we do is related to a defect in our issue tracking system, so this is not compulsory.
One last piece of information that we put in our commit comments is the name of one code reviewer. This is the person who did a sanity check on the changes before the commit takes place.
I recommend functional comments. The comments should give a summary of what was changed. If something was changed, and why. Every commit should be explainable, if you can't explain it clearly, you probably shouldn't be checking it in.
The most important thing to remember when using source control logs is they are there to determine when and what was changed. The more functional, and detailed the better. commits should be made in bite size pieces, that can be explained with bite size comments.
My personal preference is this style:
UPDATED the error logging system.
Added a legacy error parsing routine using regex to get the legacy error codes.
Changed the text in the database error messages, to correct misspellings.
Removed commented out sections of code, because they were not used any more.
The key is what are you going to do with the comments. If you're creating release notes, then you can do as you suggested. However I would recommend instead you keep track of release notes somewhere else, such as in a project management or bug tracking tool.
As for developer related comments, we've generally asked people to explain what they're doing, a one sentence explanation. It doesn't need to be too formal, mainly because if it is people will push back against it. Plus, if you know who did it, and you have a quick comment, you can generally trace back the issue and find the person.
As well, if you use a tool like FogBugz, you can link an SVN checkin to a case number. Which means that you can look up the case to get the full discussion, comments, screenshots, etc. Which is much more information than you could ever enter in a checkin comment.
Agree with Remembrance, but you should also write a little bit about why you implemented the change /bug fix the way you did.
If you belive in checking in often, you should also include TO DO's in order to make it possible for one of your co-workers to complete the task.
Making my changes small helps: I can provide detailed descriptions of my changes this way.
The checkin comments should be the information that a developer wants: this includes refactorings, motivation behind the code, etc.
On our projects we always advocate providing some detail to what a commit is about and to assist in not having to duplicate information like the problem we use Trac and have our repository integrated. The advantage is that you can then reference the issue ticket in the comment and only state the resolution or steps of work carried out. Trac then automatically links the reference number to the original issue number and applies your commit message as a comment to the issue. Then when you want to see what has been done you can simply read the issues within Trac and have full context.
With regards to release notes we have found that taking the list of issues within a release and using the commit information as a basis for the comments has worked fine. Generally you will not have release notes that have the raw commit messages in them as your clients do not really care about every little change or even the level of detail that may be included in the comment. So you would normally need to do a fair amount of editing to highlight the main changes and bug fixes implemented in that release.
I would say to try to follow a changelog style. The first line should be a short summary, and include the issue/ticket number (if any). This should possibly be followed by a blank line depending on how your VCS handles multi-line commit messages, then a fuller multiline description. I would say it's unreasonable to impose any strict formatting since it will discourage frequent commits, but so long as the important commits (the ones closing issues, or major changes) are done this way you should be ok.
If you use something like Trac or roundup + svn integration, it can pick out issue numbers from the commit messages. I would always put these in the first line since they're so useful.
Edit: Given that this is by far my most downvoted answer, I think it's worth emphasizing what's hidden in the last paragraph: I'm a sole proprietor. I have 100% ownership of these projects and do not work with other developers. In a shop with more than one developer, everything I'm saying in this answer may be completely inapposite.
I subscribe to DRY here as in all things.
I almost never add a comment to my commits. A comment is almost always repeating myself. The answer to the question "what changed in this commit"? is almost always in the diff.
When I'm looking at a file and I ask "what the hell happened here?", the first thing I do is look at the diff with the previous rev. 90% of the time the answer is immediately apparent, either because the code's self-evident or because there was something not self-evident that I commented in the code. If it's not, I correlate the rev dates of the file with the bug-tracking system and the answer is there.
This always works. It sometimes requires a little investigation to figure something out, because I didn't comment my code adequately. But I've never been unable to find the answer fairly quickly.
The only time I add a comment to the commit log is when I know that a diff isn't going to help me. For instance, when I sort a class's members: the only thing that a diff is going to tell me in that case is that something very big happened. When I do that, I commit the file as soon as I've fixed it. There's no appropriate place to comment a change of that scope in the file, so I add a comment to the effect that the only change in this rev is reordering the members.
("Why wouldn't you comment a change like that in the revision history at the top of the file?" you might ask. I don't keep a revision history at the top of my files. That was a scary, break-the-habit-of-a-lifetime change to make, and I've never regretted it for a moment. The revision history is Subversion.)
If I didn't have 100% ownership of the project, it might be different. It might be too hard to correlate commits with bug fixes. It might be too hard to train other developers to code to a style that makes it possible to rely on version control effectively. I'd have to see.