Thoughts on version control comments?

Steviemoyne

I'm a student after completing work placement and they used Team Foundation Server with Visual Studio to handle version control.

When checking in an item there was always an option to provide a check in comment, I used that feature extensively without being told to do so.

If I made changes to a method for example I would comment saying what I did, "Method X modified" , "Bug Y fixed on X method" or similar.

My questions:

What's best practice in industry for commenting version control check-ins?
Are they used much as opposed say looking at the date of a check in for a rollback or comparison purpose?
And are they used by supervisors or the like to check you're doing work and what you did?
Any other alternatives to Team Foundation Server used regularly in industry today?

This is all mainly for my own curiosity.

Thanks in advance.

CreepingDeath

We use Jira to record bugs.
So EVERYTHING that requires a code change has a Jira reference, including improvements not just bugs.

We've a validator on the SubVersion source control check-in comment, that it has to be of the format

"[<Jira Reference>] Bug description + any other comment".

Eg. "[PLAT-1000] Added support for AES encryption to security plugins".

seamus

As the above, slotting in ticket references allows for people to historically check to see what changes were made on foot of a specific ticket. It's easy enough to review changes to a specific file or a specific class, but finding out what other changes were made at the same time is harder.

A single JIRA ticket may reference a specific class that needs to be modified, but the coder or the reporter may not note in the ticket that they also had to tweak a dependent class as part of that ticket. So someone who is attempting to review that ticket may not see the additional code changes you did outside of that class.

Steviemoyne

Very interesting. I've only been exposed to Team Foundation Server as a version control tool but Jira sounds interesting. Guess I'm doing it right so, I normally try and include exactly what I changed as that's what my gut told me I should be doing.

punk_one82

Similar to above - where I work a commit to SVN without a Jira reference as a prefix will fail. The level of detail on comments comes down to the individual developer, but at the very least there's a Jira reference and a one line description of the commit.

It varies from check-in to check-in IMO. Some changes may only require a one line description, others may need a bit more of an explanation about what was done and to which classes.

seamus

I've never used TFS, but given that it's a big integrated environment I would be surprised if it's not possible to link the agile/project component to the source control one so that every check-in/commit is linked to a ticket in a project/sprint.

jester77

We also add the JIRA ticket num + what the commit is about to our git commits

The_B_Man

When we add the comment like "JIRA-123: I changed Blah.java...", the JIRA page shows what files were changed so if you only mention one file in the comments, you can refer back to JIRA and it'll give you a fuller picture.

Steviemoyne

seamus wrote: »

I've never used TFS, but given that it's a big integrated environment I would be surprised if it's not possible to link the agile/project component to the source control one so that every check-in/commit is linked to a ticket in a project/sprint.

You can link "work items" up to check ins and then have rules set up to edit the "work items". Eg: Change a work item from Approved to Committed when a check in occurs from a specific user.

They never used that feature but it was there. I got tired of how slow Visual Studio online was for creating items so I linked it into excel and created them from there which was 10 times faster.

All in all Jira sounds very interesting, I gather it's the most popular form of version control? Judging from the replies here that is.

seamus

JIRA's not version control, it's ticket management. For that, it's very popular. I think most people use either Git, TFS or some form of SVN for version control.

Steviemoyne

Ah right, I wouldn't be too familiar with anything other than Git or TFS.

Tar.Aldarion

It's not very hard to use a different one.

We too use Jira. I say what I did and then the jira ticket. Then update the jira ticket with the check in number.

Giblet

We use Youtrack which supports issuing commands via comments, as well as tagging a fix.

jester77

Tar.Aldarion wrote: »

It's not very hard to use a different one.

We too use Jira. I say what I did and then the jira ticket. Then update the jira ticket with the check in number.

There's JIRA plugins that will do that automatically for you, for SVN and git at least. They keep tabs on your history and include the diffetent commit details in your ticket.

Tar.Aldarion

Sounds good, Ill have a look, probably wont use it very much with comments I have to write on jira but may be useful

jester77

Tar.Aldarion wrote: »

Sounds good, Ill have a look, probably wont use it very much with comments I have to write on jira but may be useful

This is the one we use for git, unfortunately it's no longer free since about a year but it's well worth it for any development team.

Tar.Aldarion

Maybe something like this, https://ecosystem.atlassian.net/wiki/display/SVN/Subversion+JIRA+plugin or https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.ext.subversion
Does anybody else integrate svn with jira here?

It looks good where you can see the diffs etc

cython

Tar.Aldarion wrote: »

Maybe something like this, https://ecosystem.atlassian.net/wiki/display/SVN/Subversion+JIRA+plugin or https://marketplace.atlassian.com/plugins/com.atlassian.jira.plugin.ext.subversion
Does anybody else integrate svn with jira here?

It looks good where you can see the diffs etc

We use Crucible for code reviews, and we can integrate this (technically the Fisheye component) with Jira to show the commits for a given Jira in the ticket in a similar manner to the plugins above

Tar.Aldarion

Awesome thanks, i'd be very interested in something like this so I'm going to investigate it for work.
Our SVN doesn't use apache and our JIRA is remotely hosted so that may be a hindrance? And it would need access through our vpn to a ssh server etc which isnt good.

Anyway sorry for derailing the thread a bit, may make my own thread/research.

Steviemoyne

Tar.Aldarion wrote: »

Anyway sorry for derailing the thread a bit, may make my own thread/research.

Wouldn't consider it derailed. After finding out a good deal of version control alternatives and tools that integrate well with them. So if anyone now asks me if I've heard of Jira, SVN, Crucible etc I can actually say yes I have heard of them and I know what they do (after googling based on this threads content).

Will update the title to reflect a wider conversation. Edit: Seems I can't, but the first post has had its title updated.