Building Helpful Commit Messages

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 714600

    Comments posted to this topic are about the item Building Helpful Commit Messages

  • peter.row

    SSCarpal Tunnel

    Points: 4290

    I echo the articles post, we use JIRA for tasks and the number 1 rule for all developers is you must put the task ID in the commit message, no if's, ands or buts about it. Any other text is syntatic sugar after that.

  • Jeff Moden

    SSC Guru

    Points: 993863

    Heh... good comments both simplify and rule the world.  It's too bad that people don't understand that comments external to the code, even in a VCS, are too easily lost.  We make sure that properly documented revision history is included in the flower box of the T-SQL code.  I'm not privy to how the front-enders do things in SVN (for now, we're moving to Jira... hope it's a change that's a change for the better and not just a change).

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column.
    "If you think its expensive to hire a professional to do the job, wait until you hire an amateur."--Red Adair
    "Change is inevitable... change for the better is not."
    When you put the right degree of spin on it, the number 3|8 is also a glyph that describes the nature of a DBAs job. 😉

    Helpful Links:
    How to post code problems

  • peter.row

    SSCarpal Tunnel

    Points: 4290

    JIRA has a really nice plug-in called Crucible for code reviews that automatically signposts you to the commits made to that task.

    For example, say I have task MP-1234, I do the work and in the commit message I put MP-1234. Crucible will automatically pick out the task ID from the commit message so that when I go back to the task in JIRA there is a "Development" section on the page that will allow me to create a review from the commits made that mention that task in the commit comments. Crucible provides a web front end for diffing the changed files and allows the reviewer to comment on specific lines of code and mark them as "needs resolving". Thus when you reopen a task the developer can see specifically which bit of the code you are talking about easily with not much effort on either side.

    If you're losing comments in your VCS then something is wrong, the whole point of VCS is so that you can look back at changes and what happened. We use to write revision historys in T-SQL SPs and the like but it gets ridiculous in a long running application where an SP might get changed 30 times over a few years and thus the comments are longer than the actual SQL. In the end do you really care what things were like in an SP 3 years ago? When debugging it's normally going to be recent changes you look at or whether it was broken in the previous release or not. Plus a diff of an SP speaks a lot more than a comment when you want to know what the actual change was.

  • Jeff Moden

    SSC Guru

    Points: 993863

    Awesome.  Thanks for the tips on the use of Crucible.

    As far as losing comments in our VCS goes, we don't.  What we are going to lose is ALL of the history because someone decided to change from SVN to Jira (I don't know if there's a migration path there but the people "in charge" said no attempt will be made).  Only comments in the code will survive the onslaught.  The same goes with our ticketing system.  This will be the 3rd time they've changed it and the information in the tickets important... and yet they'll be making no migration attempt there, either.

    The fortunate thing on that latter part about the ticketing system is that it is SQL Server based.  You can bet that I'll be preserving that little database for a long time to come.

    Also, totally agreed that a DIFF on an SP to see what the changes were is the absolute best but, like I said, when people change VCSs, it's a bit difficult to do for anything that straddles the change.  Of course, that's only a temporary issue but, again, any notes from the previous VCS will be lost and the comments in the code will not.  And, yeah... sometimes it is actually important to know what a ticket number from 28 changes ago actually was.  Of course, they've also shot that to hell by changing ticketing systems for a 3rd time in less than 7 years, all without any migration effort.

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column.
    "If you think its expensive to hire a professional to do the job, wait until you hire an amateur."--Red Adair
    "Change is inevitable... change for the better is not."
    When you put the right degree of spin on it, the number 3|8 is also a glyph that describes the nature of a DBAs job. 😉

    Helpful Links:
    How to post code problems

  • peter.row

    SSCarpal Tunnel

    Points: 4290

    Oh in that case you won't lose anything. JIRA is a task management system it is not a VCS. We use SVN for VCS and JIRA for task management.

  • Jeff Moden

    SSC Guru

    Points: 993863

    peter.row wrote:

    Oh in that case you won't lose anything. JIRA is a task management system it is not a VCS. We use SVN for VCS and JIRA for task management.

    Ah... my apologies... I've lumped it all together.  They're moving from SVN to "BitBucket" and, because of the association with GitHub (or at least in my poor mind due to unfamiliarity), I lumped that together with Jira.

    --Jeff Moden


    RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
    First step towards the paradigm shift of writing Set Based code:
    ________Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column.
    "If you think its expensive to hire a professional to do the job, wait until you hire an amateur."--Red Adair
    "Change is inevitable... change for the better is not."
    When you put the right degree of spin on it, the number 3|8 is also a glyph that describes the nature of a DBAs job. 😉

    Helpful Links:
    How to post code problems

  • Eric M Russell

    SSC Guru

    Points: 124965

    The problem is that many organizations simply deploy a VCS solution and then put out the word that everybody should start using it. But it's not just another developer tool, it's essentially process and collaboration tool. To be effective, everyone on the team needs to understand more than just the bare necessities of how to clone a repository and commit.

    "Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 714600

    Looks like svn -> git shouldn't be hard. Convert it, then load to Bitbucket

    https://blokspeed.net/blog/2010/09/converting-from-subversion-to-git

    Git is better, way better, IMHO, but it's just a repo. Comments need not be lost.

  • Chris Harshman

    SSC-Forever

    Points: 41661

    I think where I'm at we tend to "loose" the comments in our VCS because the developers feature branch everything, so unless you know what branch the change was actually made in, most of the version history comments just look like "merged from dev" etc.  Throughout my career I've also preferred the methodology of having the change history in a comment header in the code script.

  • Steve Jones - SSC Editor

    SSC Guru

    Points: 714600

    That's a skill in and of itself. Comments should go through the PR, but if not, I would hope your client allowed click through to the original branch for the comment.

  • Data_Cat

    SSC Enthusiast

    Points: 148

    I work for a small company that has three people who work with SQL and VB.net. We are very interested in learning how to use a Version Control System, and the best practices of doing so. We are a Microsoft shop, and so thought we should be using Azure DevOps (used to be Microsoft Team Foundation Services)  for version control. We have looked around some, but can't find any resources to really help us get started. Does anyone know of any good training materials to get us up and running? What is the consensus here? Is Git the better route to go now?

    Thanks!

    P.S. We are also considering using JIRA if that influences anything.

  • peter.row

    SSCarpal Tunnel

    Points: 4290

    Data_Cat wrote:

    I work for a small company that has three people who work with SQL and VB.net. We are very interested in learning how to use a Version Control System, and the best practices of doing so. We are a Microsoft shop, and so thought we should be using Azure DevOps (used to be Microsoft Team Foundation Services)  for version control. We have looked around some, but can't find any resources to really help us get started. Does anyone know of any good training materials to get us up and running? What is the consensus here? Is Git the better route to go now? Thanks! P.S. We are also considering using JIRA if that influences anything.

    Git is the one that everyone is on or moving to so if you haven't used a VCS before you may as well start by learning that.

    For me I've only ever used SVN and Git is a lot more complex and diffcult to use. Thus when I was thrust into using it for a brief period with no training or help just "use it" then that has kind of soured my view of it. I know it's technically better, especially so in distrubed environments, but like 99% of the time I always want to push my changes back to the central repo, whether that be file changes or tags/branches all of which is a 2 step process instead of one unless you have a tool you configure to always do that.

    I also find that there is no one visual tool that can do everything with Git. For SVN I would just install TortoiseSVN and I was done. With Git I tried 3 or 4 different tools and ultimately always ended up at the command line to do things eventually.

  • peter.row

    SSCarpal Tunnel

    Points: 4290

    Chris Harshman wrote:

    I think where I'm at we tend to "loose" the comments in our VCS because the developers feature branch everything, so unless you know what branch the change was actually made in, most of the version history comments just look like "merged from dev" etc.  Throughout my career I've also preferred the methodology of having the change history in a comment header in the code script.

    We are currently using SVN and TortoiseSVN, when you merge a branch in then it helpful lets you select/include all the commit messages from that branch; thus developers making feature branches has no bearing and doesn't lose any comments.

     

  • mfagan12

    SSC Eights!

    Points: 966

    Data_Cat wrote:

    I work for a small company that has three people who work with SQL and VB.net. We are very interested in learning how to use a Version Control System, and the best practices of doing so. We are a Microsoft shop, and so thought we should be using Azure DevOps (used to be Microsoft Team Foundation Services)  for version control. We have looked around some, but can't find any resources to really help us get started. Does anyone know of any good training materials to get us up and running? What is the consensus here? Is Git the better route to go now? Thanks! P.S. We are also considering using JIRA if that influences anything.

     

    Your shop sounds the same as mine.  We went from using Subversion to TFS and out of our 3 person team, I was the only one who didn't have experience using TFS.  Funny thing was that I was able to get the server set up and get the permissions set up--that was the easiest part to find information online about but like you, finding any training or videos related to the most current version--I didn't have much luck.  I bought the one book I could find and then had the 2 other people write up instructions with screen shots and now I feel comfortable using it.  We're still not using every feature of it but given that we have MSDN subscriptions and have to follow certain guidelines about using 3rd party software, TFS was the best route for us to go.

     

Viewing 15 posts - 1 through 15 (of 15 total)

You must be logged in to reply to this topic. Login to reply