Process>Issue and Change Management
You will note that we intend for this to be light-hearted! How else are we to have fun with "standards". :-)
Bottom line is good issue and change management gives us and our end customers the following benefits:
- When issues are raised in the support forums and a true issue is identified, it gets logged into the Mantis Bug Tracker System so we do not lose track of it (we're all VERY busy and so to rely on memory or each of us having our own methods, just does not make sense)
- It helps us to plan our next release (roadmap)
- It helps us to give a clear Change Log to the end customers
- It helps us to track down the discussion and reasons for every change that is made to the code - this helps us to support the product better, as well as to help all of us to know what is changing from release to release
These are only a few that quickly came to mind. There are sure to be others.
Our standard tool for tracking our issues (which include enhancements and bugs) is Mantis. (Sorry, not going to give out the URL!) In order to meet the expectations for issue management laid out above, we need to be diligent in doing the following:
Every Change Needs an Issue - This pretty much goes without saying. If we cannot tie a change to an issue, we have no idea the reasons why the change was made. This goes for enhancements as well as for raised bugs. However, what about bugs that we introduce during the development of a release? (Yes, we're not perfect...lol) Either the original Issue is re-opened which infused the bug, or a new Issue is created. Bugs that we introduce in prior releases (that are already released) should have new Mantis issues to address (think "Change Log").
"Resolved" vs. "Closed" - The Change Status is important as it affects how we keep track of the status of the issue, but when it comes to completing the issue, there are two statuses to consider. There are going to be times when an issue is raised that we find out later no change is needed. Since there was no change, we do not want/need the Change Log to reflect a non-existent change. Therefore, in this case, and this case only, please use "Closed". For all other completions, we should use "Resolved". In either case, a brief summary should be given as to the final results (use your judgment, but just keep in mind that we're not mind readers, so if it seems like there would be some helpful text to convey, feel free to do so).
Target Version - This is an important field and helps to drive the Road Map feature of Mantis. Every issue upon being opened is to be given a "Target Version". The current release version will always be available to choose here, but if you feel that a different version should be used and its not there, just ask Raven or another administrator to add it.
Fixed In Version - This is another important field and helps to drive the Change Log feature of Mantis (it saves us a ton of time pulling together the detailed change log to go with the release documentation!). Upon marking an Issue as Resolved, please mark the release version it was resolved in.
Issue Summary Text - Again, just think Change Log as the issue summary is automatically placed into that log. Just try to make they read well and are reflective of the change being made.
Internal Bugs to a Release - These are bugs that were introduced during the course of a given release development cycle, but were fixed WITHIN that release (i.e., never was released to the public). These can be handled one of two ways: 1) document the bug and the SVN comment with the Mantis issue which infused the bug, or 2) create a new Mantis issue, but make the Issue title have "[INTERNAL]" in front like this:
0001157: [INTERNAL] Notice when changing user password via admin panel
Product Build - As an issue is Resolved, ensure this is given the value of the SVN revision number(s) where the issue was committed in. Remember, as much as possible, only complete and fully tested code is supposed to get committed to the repository, so this build number should be all inclusive of the changes related to a given issue. On occassion, changes are quite extensive and it may be desirable to commit often. This should be exception rather than the rule, and the final commit revision number is what should be marked here.
Our change control tool is Subversion. Keep these things in mind regarding change control:
Release Versions - Our standard version format is as follows:
where a change in A would signal a major re-write or core engine type of change. A change in BB signals a change in functionality, which may or may not include a database-level change. A change in CC signals a patch level change and is almost always just a change at the file level (but, if a problem exists which requires a DB fix, we'll definitely include DB updates in a CC level change).
Subversion Client - The standard for a windows desktop subversion client has been Tortoise. It really does not matter what client is used, but this one is excellent. Whatever client is used, make sure to keep it updated and that the client approach is to remain backward compatible.
Trunk vs. Branch vs. Tag - All A or BB level development shall be done on the trunk unless otherwise communicated. We don't have the resources to maintain multiple branches of development, so we're pretty much sequential. However, in order to facilitate quicker release patches, new branches may be cut at the A or B level where all patch-only changes shall occur. These patches will be merged into the trunk on a periodic basis. Tags shall always be used to mark the released revision. Tags shall be created ONLY by Raven, as the release manager. Branches should also be created by Raven or a designee.
Always Update Prior to Commmit - This is very important as it has caused us some grief in the past. Due to team collaboration on our code, it is possible for multiple people to be updating the same script at the same time. ALWAYS run an SVN update on your scripts just prior to committing them! Thanks!
Conflict Resolution - If when you perform the above update, you find that other code changes have been merged into yours OR a conflict occurs (subversion will tell you when this occurs), more action must be taken. If other code changes are merged into yours, it would be a good idea to re-test that portion of the code if you think there could be any issues with the code changes you have to commit. If there are conflicts, well, read the help within Tortoise as to how to deal with those. This means that you have modified a line of code that someone else has committed changes to! If you just commit your changes, everybody's working copies, upon an update, will be broken!
Change Description - It is important within the change description (called "Change Message" in the client) back to the Mantis Issue which drove the change (that is where the discussion and/or reasons for the change are kept, plus the tie back to the Change Log). It is also helpful to provide a brief description of the change that was made. No need to go "hog wild" here as one can always do a revision diff and see the changed code. Just consider what would be helpful to someone to quickly get a sense for the change and/or amount of change.
Just as a helpful "hint", it is extremely easy when you are in your issue, to just copy the whole Summary text line and paste it up-front into your change description. For example:
0000968: Allow users to set maximum number of items per feed
That sure gives a nice clean and very clear "picture" of what that change was!