From mtaylor at redhat.com Tue Sep 23 10:48:46 2014 From: mtaylor at redhat.com (Martyn Taylor) Date: Tue, 23 Sep 2014 15:48:46 +0100 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow Message-ID: <5421884E.2050302@redhat.com> Hi All, So when I first started a few of you asked me to speak up if I noticed areas where I think we may be able to do things better. So here goes :P Just a quick email regarding our work flow for committing changes to HornetQ and hopefully two areas that will take very little effort to change but might make our development cycle a little smoother. The two things I'm thinking of are the way we are using close PR for reviews and how we structure our commit messages. So... Closing PRs after review: We are currently using the Fork and Pull model using GitHub pull requests. https://help.github.com/articles/closing-a-pull-request. One slight difference is that we tend to review pull requests then close them if any changes need to be made. This has it's advantages in that it can reduce the amount of open pull requests (which makes it easier for reviewers to identify what needs reviewing) leaving it to down to the PR owner to address changes (fix tests, code changes, styling etc...). Once the changes have been made the PR owner can then reopen the PR and it will appear again for reviewers to review. However there are a couple of downsides to this approach. In the typical the typical fork/pull model the PR owner (once recieving feedback) will likely go away and make changes to his/her fork. The history of the developer fork is not of importance and it is typical for developers to rebase commits and force push their own fork. However, once a PR has been closed and the developer has forced pushed to the fork they opened the PR from, it is no longer able to be reopened. This kind of makes sense, as closing a PR in the context of the GitHub fork/pull model means that this PR is no longer relevant and the close is meant to be permanent (Though GitHub offers a get out clause by offering a re-open option): The only way (at least from what I can gather) to get around this problem is to open a new PR based on the developers fork/branch (that has been forced pushed to). However this does result in having numerous PRs based on the same fork/branch being present in the closed PR list. This can sometimes cause confusion of which closed PR is the one the developer needs to comment on or to update. I've done it myself and went to comment on a PR that was closed, not realising I was actually commenting on an older version of the PR. Also opening a new PR does mean that we lose the discussion history. Which is often useful, particularly to add context. For larger changes where there is a fair amount of back and forth (review, change, review, change) etc... this is really helpful. Lastly one other scenario where closing the PR is a cumbersome is when the branch that PR is based on was not rebased onto master. Again I've done this myself... pushed up a change to my fork without running `git rebase hornetq/master`. This can sometimes result in extra commits showing in the PR. There is a quick fix for this: run rebase and force push to the fork/branch and the PR will reflect the changes immediately. However if the PR was closed before fork/branch is rebased, it is no longer possible to reopen it again (as the force push was made). Due to this I'd like to suggest that we move away from closing PRs when changes need to be made. Instead we can simply leave the PR open whilst it is being reworked, GitHub notifications take care of letting us know when a new PR has been opened, when a PR has been commented on and also when PR has been updated. So I don't think that leaving PRs open is going to cause confusion. It is actually the normal way that the GitHub pull and fork mechanism is meant to work: https://help.github.com/articles/using-pull-requests. What do others think about this? Structuring commit messages... The other work flow related suggestion I'd like to make is how we structure our git commit messages. There is a best practice for writing git commit messages using (50/72) styling, see: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. In short, the idea really is to add a very short summary of the message in the title, followed by a new line then description. This makes it easier to identify commits when looking at the commit log in various git tools. An example could be something like this: """ HQ-1343 Added new logger for JMS Bridge This commit adds a new logger dedicated to the JMS Bridge. This allows users to identify log messages that are coming from the bridge aiding identification of bridge failures. """ Using a git tool like gitk for example to view the commits, I get all the relevant information on 1 line: """ HQ-1343 Added new logger for JMS Bridge mtaylor at redhat.com 22/09/2014 """ Also, setting up and editor like vim is really easy and will add syntax highlighting for the 50/72 git commit style. Commits in HQ with a large 1 liner title or with a URL as the first thing are difficult to read. The equivilent view in gitk for messaging like this shows something like: """ https://bugzilla.redhat.com/show_bug.cgi?id... mtaylor at redhat.com 22/09/2014 """ Which doesn't really offer me any information other than the date and committer. Regardless of whether we decide to use 50/72 style. I'd like to get your thoughts on using a format something along the lines of this: """ Short summary """ All the relevant information is on the first line. JIra reference and summary. Then more detailed description and references are added in a detailed description below. Useful if we need to find out more information about the commit. Please let me know what your thoughts are. Regards Martyn From csuconic at redhat.com Tue Sep 23 11:12:02 2014 From: csuconic at redhat.com (Clebert Suconic) Date: Tue, 23 Sep 2014 11:12:02 -0400 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <5421884E.2050302@redhat.com> References: <5421884E.2050302@redhat.com> Message-ID: <637A331E-F771-445A-9EED-C1D2AEC1641F@redhat.com> I'm fine with that... lets start not closing PRs then!.... let me add some background for why we were doing it. The reason we started closing the PRs wasn't to keep the list low... was to avoid someone without the context of the PR to merge it. Say you guys worked during your day in UK, when I start working in US (say if I started working later that day) and you guys are already sleeping.. if I see a PR open I could merge it even though it wasn't valid yet. (It had happened before we started closing PRs) if github didn't have a bug it would all be good..... Regarding commit messages... +1... lets start having some better way to communicate changes. Currently our format is BZ|JIRA - short message For non bug-fixes (small config changes.. etc).. we just have a short message... I like the way Netty does their commit messages Title Motivation: Why you're making the change Modifications: what was changed Result: The output... Even though that probably duplicates JIRA... it gives some context when looking at the github logs. github logs gets a lot more useful (mainly for me when I'm talking to support guys.. etc). I'm open for discussion on the commit messages.. if you guys think it's too verbose.. we can use that On Sep 23, 2014, at 10:48 AM, Martyn Taylor wrote: > Hi All, > > So when I first started a few of you asked me to speak up if I noticed > areas where I think we may be able to do things better. So here goes :P > > Just a quick email regarding our work flow for committing changes to > HornetQ and hopefully two areas that will take very little effort to > change but might make our development cycle a little smoother. > > The two things I'm thinking of are the way we are using close PR for > reviews and how we structure our commit messages. > > So... Closing PRs after review: > > We are currently using the Fork and Pull model using GitHub pull > requests. https://help.github.com/articles/closing-a-pull-request. > > One slight difference is that we tend to review pull requests then close > them if any changes need to be made. This has it's advantages in that > it can reduce the amount of open pull requests (which makes it easier > for reviewers to identify what needs reviewing) leaving it to down to > the PR owner to address changes (fix tests, code changes, styling > etc...). Once the changes have been made the PR owner can then reopen > the PR and it will appear again for reviewers to review. > > However there are a couple of downsides to this approach. In the > typical the typical fork/pull model the PR owner (once recieving > feedback) will likely go away and make changes to his/her fork. The > history of the developer fork is not of importance and it is typical for > developers to rebase commits and force push their own fork. However, > once a PR has been closed and the developer has forced pushed to the > fork they opened the PR from, it is no longer able to be reopened. > This kind of makes sense, as closing a PR in the context of the GitHub > fork/pull model means that this PR is no longer relevant and the close > is meant to be permanent (Though GitHub offers a get out clause by > offering a re-open option): > > The only way (at least from what I can gather) to get around this > problem is to open a new PR based on the developers fork/branch (that > has been forced pushed to). However this does result in having numerous > PRs based on the same fork/branch being present in the closed PR list. > This can sometimes cause confusion of which closed PR is the one the > developer needs to comment on or to update. I've done it myself and > went to comment on a PR that was closed, not realising I was actually > commenting on an older version of the PR. > > Also opening a new PR does mean that we lose the discussion history. > Which is often useful, particularly to add context. For larger changes > where there is a fair amount of back and forth (review, change, review, > change) etc... this is really helpful. > > Lastly one other scenario where closing the PR is a cumbersome is when > the branch that PR is based on was not rebased onto master. Again I've > done this myself... pushed up a change to my fork without running `git > rebase hornetq/master`. This can sometimes result in extra commits > showing in the PR. There is a quick fix for this: run rebase and force > push to the fork/branch and the PR will reflect the changes > immediately. However if the PR was closed before fork/branch is > rebased, it is no longer possible to reopen it again (as the force push > was made). > > Due to this I'd like to suggest that we move away from closing PRs when > changes need to be made. Instead we can simply leave the PR open whilst > it is being reworked, GitHub notifications take care of letting us know > when a new PR has been opened, when a PR has been commented on and also > when PR has been updated. So I don't think that leaving PRs open is > going to cause confusion. It is actually the normal way that the GitHub > pull and fork mechanism is meant to work: > https://help.github.com/articles/using-pull-requests. > > What do others think about this? > > Structuring commit messages... > > The other work flow related suggestion I'd like to make is how we > structure our git commit messages. There is a best practice for writing > git commit messages using (50/72) styling, see: > http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. In > short, the idea really is to add a very short summary of the message in > the title, followed by a new line then description. This makes it > easier to identify commits when looking at the commit log in various git > tools. > > An example could be something like this: > > """ > HQ-1343 Added new logger for JMS Bridge > > This commit adds a new logger dedicated to the JMS Bridge. This allows > users to identify log messages that are coming from the bridge aiding > identification of bridge failures. > """ > > Using a git tool like gitk for example to view the commits, I get all > the relevant information on 1 line: > > """ > HQ-1343 Added new logger for JMS Bridge mtaylor at redhat.com > 22/09/2014 > """ > > Also, setting up and editor like vim is really easy and will add syntax > highlighting for the 50/72 git commit style. > > Commits in HQ with a large 1 liner title or with a URL as the first > thing are difficult to read. The equivilent view in gitk for messaging > like this shows something like: > > """ > https://bugzilla.redhat.com/show_bug.cgi?id... > mtaylor at redhat.com 22/09/2014 > """ > > Which doesn't really offer me any information other than the date and > committer. > > Regardless of whether we decide to use 50/72 style. I'd like to get > your thoughts on using a format something along the lines of this: > > """ > Short summary > > > > > """ > > All the relevant information is on the first line. JIra reference and > summary. Then more detailed description and references are added in a > detailed description below. Useful if we need to find out more > information about the commit. > > > Please let me know what your thoughts are. > > Regards > Martyn > _______________________________________________ > hornetq-dev mailing list > hornetq-dev at lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hornetq-dev From mtaylor at redhat.com Tue Sep 23 11:25:02 2014 From: mtaylor at redhat.com (Martyn Taylor) Date: Tue, 23 Sep 2014 16:25:02 +0100 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <637A331E-F771-445A-9EED-C1D2AEC1641F@redhat.com> References: <5421884E.2050302@redhat.com> <637A331E-F771-445A-9EED-C1D2AEC1641F@redhat.com> Message-ID: <542190CE.6060106@redhat.com> On 23/09/14 16:12, Clebert Suconic wrote: > I'm fine with that... lets start not closing PRs then!.... let me add some background for why we were doing it. > > > > The reason we started closing the PRs wasn't to keep the list low... was to avoid someone without the context of the PR to merge it. > Say you guys worked during your day in UK, when I start working in US (say if I started working later that day) and you guys are already sleeping.. if I see a PR open I could merge it even though it wasn't valid yet. (It had happened before we started closing PRs) > Sure I can understand that. It probably makes sense to leave it down to the developer to decide if they have enough information to review the PR. For smaller changes the JIRA and/or Commit message should suffice. For cases where there has been some offline communication between particular people we should probably assign the PR to a particular person for review. (I did yesterday with Andy). Also if the PR is not ready to be merged but is only up for review, we can add a "Work in progress" comment on the PR to avoid others merging. > > > if github didn't have a bug it would all be good..... I'm not sure if GH has bugs or if we are just not using it in the right manner :p. Either way complying with whatever GitHub expects should make our lives easier. :) > > > > > > > Regarding commit messages... +1... lets start having some better way to communicate changes. > > > Currently our format is BZ|JIRA - short message > > > For non bug-fixes (small config changes.. etc).. we just have a short message... > > > > > > > > I like the way Netty does their commit messages > > > Title > > Motivation: > Why you're making the change > > Modifications: > what was changed > > > Result: > The output... > > > > > Even though that probably duplicates JIRA... it gives some context when looking at the github logs. github logs gets a lot more useful (mainly for me when I'm talking to support guys.. etc). Sure. I like this style. The Motivation/Modification/Result format may be a little too verbose for making smaller changes, but the developer/reviewer could just make a call on when the extra info is necessary. It would also be good to have references to JIRA or BZs in there also. Perhaps Title Motivation: Why you're making the change Modifications: what was changed Result: The output... > > > > > > > I'm open for discussion on the commit messages.. if you guys think it's too verbose.. we can use that Thanks Clebert. > > On Sep 23, 2014, at 10:48 AM, Martyn Taylor wrote: > >> Hi All, >> >> So when I first started a few of you asked me to speak up if I noticed >> areas where I think we may be able to do things better. So here goes :P >> >> Just a quick email regarding our work flow for committing changes to >> HornetQ and hopefully two areas that will take very little effort to >> change but might make our development cycle a little smoother. >> >> The two things I'm thinking of are the way we are using close PR for >> reviews and how we structure our commit messages. >> >> So... Closing PRs after review: >> >> We are currently using the Fork and Pull model using GitHub pull >> requests. https://help.github.com/articles/closing-a-pull-request. >> >> One slight difference is that we tend to review pull requests then close >> them if any changes need to be made. This has it's advantages in that >> it can reduce the amount of open pull requests (which makes it easier >> for reviewers to identify what needs reviewing) leaving it to down to >> the PR owner to address changes (fix tests, code changes, styling >> etc...). Once the changes have been made the PR owner can then reopen >> the PR and it will appear again for reviewers to review. >> >> However there are a couple of downsides to this approach. In the >> typical the typical fork/pull model the PR owner (once recieving >> feedback) will likely go away and make changes to his/her fork. The >> history of the developer fork is not of importance and it is typical for >> developers to rebase commits and force push their own fork. However, >> once a PR has been closed and the developer has forced pushed to the >> fork they opened the PR from, it is no longer able to be reopened. >> This kind of makes sense, as closing a PR in the context of the GitHub >> fork/pull model means that this PR is no longer relevant and the close >> is meant to be permanent (Though GitHub offers a get out clause by >> offering a re-open option): >> >> The only way (at least from what I can gather) to get around this >> problem is to open a new PR based on the developers fork/branch (that >> has been forced pushed to). However this does result in having numerous >> PRs based on the same fork/branch being present in the closed PR list. >> This can sometimes cause confusion of which closed PR is the one the >> developer needs to comment on or to update. I've done it myself and >> went to comment on a PR that was closed, not realising I was actually >> commenting on an older version of the PR. >> >> Also opening a new PR does mean that we lose the discussion history. >> Which is often useful, particularly to add context. For larger changes >> where there is a fair amount of back and forth (review, change, review, >> change) etc... this is really helpful. >> >> Lastly one other scenario where closing the PR is a cumbersome is when >> the branch that PR is based on was not rebased onto master. Again I've >> done this myself... pushed up a change to my fork without running `git >> rebase hornetq/master`. This can sometimes result in extra commits >> showing in the PR. There is a quick fix for this: run rebase and force >> push to the fork/branch and the PR will reflect the changes >> immediately. However if the PR was closed before fork/branch is >> rebased, it is no longer possible to reopen it again (as the force push >> was made). >> >> Due to this I'd like to suggest that we move away from closing PRs when >> changes need to be made. Instead we can simply leave the PR open whilst >> it is being reworked, GitHub notifications take care of letting us know >> when a new PR has been opened, when a PR has been commented on and also >> when PR has been updated. So I don't think that leaving PRs open is >> going to cause confusion. It is actually the normal way that the GitHub >> pull and fork mechanism is meant to work: >> https://help.github.com/articles/using-pull-requests. >> >> What do others think about this? >> >> Structuring commit messages... >> >> The other work flow related suggestion I'd like to make is how we >> structure our git commit messages. There is a best practice for writing >> git commit messages using (50/72) styling, see: >> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. In >> short, the idea really is to add a very short summary of the message in >> the title, followed by a new line then description. This makes it >> easier to identify commits when looking at the commit log in various git >> tools. >> >> An example could be something like this: >> >> """ >> HQ-1343 Added new logger for JMS Bridge >> >> This commit adds a new logger dedicated to the JMS Bridge. This allows >> users to identify log messages that are coming from the bridge aiding >> identification of bridge failures. >> """ >> >> Using a git tool like gitk for example to view the commits, I get all >> the relevant information on 1 line: >> >> """ >> HQ-1343 Added new logger for JMS Bridge mtaylor at redhat.com >> 22/09/2014 >> """ >> >> Also, setting up and editor like vim is really easy and will add syntax >> highlighting for the 50/72 git commit style. >> >> Commits in HQ with a large 1 liner title or with a URL as the first >> thing are difficult to read. The equivilent view in gitk for messaging >> like this shows something like: >> >> """ >> https://bugzilla.redhat.com/show_bug.cgi?id... >> mtaylor at redhat.com 22/09/2014 >> """ >> >> Which doesn't really offer me any information other than the date and >> committer. >> >> Regardless of whether we decide to use 50/72 style. I'd like to get >> your thoughts on using a format something along the lines of this: >> >> """ >> Short summary >> >> >> >> >> """ >> >> All the relevant information is on the first line. JIra reference and >> summary. Then more detailed description and references are added in a >> detailed description below. Useful if we need to find out more >> information about the commit. >> >> >> Please let me know what your thoughts are. >> >> Regards >> Martyn >> _______________________________________________ >> hornetq-dev mailing list >> hornetq-dev at lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hornetq-dev From jmesnil at redhat.com Wed Sep 24 09:24:07 2014 From: jmesnil at redhat.com (Jeff Mesnil) Date: Wed, 24 Sep 2014 15:24:07 +0200 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <5421884E.2050302@redhat.com> References: <5421884E.2050302@redhat.com> Message-ID: <8EEF81CA-7DF5-424B-8509-1929E9284B08@redhat.com> It?d also be great if you could give bidirectional links between JIRA issues and GitHub PRs. When I look at a resolved issue in JIRA and want to see the corresponding commits in GitHub, it?s always a PITA. You already proposed to add the JIRA link in the commit message. The only other step is to set the PR link in the JIRA issue using the ?Git Pull Request?. jeff From mtaylor at redhat.com Wed Sep 24 09:29:05 2014 From: mtaylor at redhat.com (Martyn Taylor) Date: Wed, 24 Sep 2014 14:29:05 +0100 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <8EEF81CA-7DF5-424B-8509-1929E9284B08@redhat.com> References: <5421884E.2050302@redhat.com> <8EEF81CA-7DF5-424B-8509-1929E9284B08@redhat.com> Message-ID: <5422C721.3040700@redhat.com> Makes sense Jeff. I know for other Project management tools there are integration points with GH that allows us just to set the ticket ID in the commit message. The agent/integration piece would then update the ticket in the project management tool. I'll see if there is something similar for JIRA. Otherwise I personally have no problem in manually adding a reference to the PR or commit in JIRA. On 24/09/14 14:24, Jeff Mesnil wrote: > It?d also be great if you could give bidirectional links between JIRA issues and GitHub PRs. > > When I look at a resolved issue in JIRA and want to see the corresponding commits in GitHub, it?s always a PITA. > > You already proposed to add the JIRA link in the commit message. > The only other step is to set the PR link in the JIRA issue using the ?Git Pull Request?. > > jeff > From jmesnil at redhat.com Wed Sep 24 09:35:04 2014 From: jmesnil at redhat.com (Jeff Mesnil) Date: Wed, 24 Sep 2014 15:35:04 +0200 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <5422C721.3040700@redhat.com> References: <5421884E.2050302@redhat.com> <8EEF81CA-7DF5-424B-8509-1929E9284B08@redhat.com> <5422C721.3040700@redhat.com> Message-ID: <25DD1DF9-5EE2-4A15-850A-D528B3BD8DEA@redhat.com> On 24 Sep 2014, at 15:29, Martyn Taylor wrote: > Makes sense Jeff. > > I know for other Project management tools there are integration points with GH that allows us just to set the ticket ID in the commit message. The agent/integration piece would then update the ticket in the project management tool. I'll see if there is something similar for JIRA. Otherwise I personally have no problem in manually adding a reference to the PR or commit in JIRA. WildFly?s JIRA uses the "GIT Pull Request workflow?. You could also use it, I think. -- Jeff Mesnil JBoss, a division of Red Hat http://jmesnil.net/ From mtaylor at redhat.com Wed Sep 24 09:36:55 2014 From: mtaylor at redhat.com (Martyn Taylor) Date: Wed, 24 Sep 2014 14:36:55 +0100 Subject: [hornetq-dev] Suggestions for enhancing HornetQ development work flow In-Reply-To: <25DD1DF9-5EE2-4A15-850A-D528B3BD8DEA@redhat.com> References: <5421884E.2050302@redhat.com> <8EEF81CA-7DF5-424B-8509-1929E9284B08@redhat.com> <5422C721.3040700@redhat.com> <25DD1DF9-5EE2-4A15-850A-D528B3BD8DEA@redhat.com> Message-ID: <5422C8F7.3080709@redhat.com> On 24/09/14 14:35, Jeff Mesnil wrote: > On 24 Sep 2014, at 15:29, Martyn Taylor wrote: > >> Makes sense Jeff. >> >> I know for other Project management tools there are integration points with GH that allows us just to set the ticket ID in the commit message. The agent/integration piece would then update the ticket in the project management tool. I'll see if there is something similar for JIRA. Otherwise I personally have no problem in manually adding a reference to the PR or commit in JIRA. > WildFly?s JIRA uses the "GIT Pull Request workflow?. You could also use it, I think. > I'll take a look. It may well already be there, it could just be that we are not using the magic words. Cheers.