geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Dillon <ja...@planet57.com>
Subject Re: [DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification please from the PMC )
Date Sat, 01 Jul 2006 09:31:52 GMT
SVN changes that are associated with a JIRA should include the JIRA  
id (exact case) so that JIRA can link back to the changes.

--jason


On Jun 30, 2006, at 6:56 PM, John Sisson wrote:

> In the "Re: [RTC] Clarification please from the PMC" thread I  
> raised some issues regarding documenting changes made to the code  
> and impacts on the RTC process, other developers and end users.
>
> Here is a summary of those comments:
>
> There have been JIRAs for commits/RTCs where in the mailing list  
> they have been described as a major enhancement, yet the JIRA does  
> not even have a description or comments.  The lack of information  
> about the changes in the JIRA makes it harder for others to review  
> the change.  Developers should not assume that they will just be  
> able to explain their change via IRC to those reviewing it.   
> Everyone isn't in a suitable timezone to chat with the developer  
> making the change.  More documentation needs to be placed in the  
> JIRAs and the Wiki.
>
> Lack of information also means that it will be unlikely that the  
> change will be identified as needing to be documented in the  
> manuals and possibly migration information in the release notes.   
> Users picking up the next release will see the JIRA entry and may  
> ask questions on what the change is or how they should use it on  
> the mailing list, adding to the load of everyone's inbox.
>
> All code change JIRAs should have adequate information in them for  
> people to be able to review and test a change.  This information  
> can then be used as a seed for documenting the changes in further  
> detail in the wiki/manuals (if the change impacts end users).  Any  
> enhancement/change that should be discussed in the manuals should  
> have another JIRA created for the documentation task for it.
> FOR DISCUSSION:
>
> 1. Any change that end users may have visibility of should have a  
> documentation task JIRA created for it and the documentation JIRA  
> task should be linked to the JIRA for the change.  Examples of  
> these are:
>
> - Changes to external APIs, command line tools
> - Changes to configuration formats
> - Changes that require the user to perform migration tasks when  
> moving from a previous release to this release
> - New functionality
> - ?? Anything else?
>
> 2. The documentation task is where the documentation should be  
> discussed and shouldn't be closed until the documentation is in the  
> wiki.  There should be enough information in the code change JIRA  
> to get started on the documentation task.
>
> 3. What type of JIRA linking should we use between the code change  
> JIRA and the documentation task JIRA?  I'm not sure whether in our  
> current JIRA setup whether a parent issue can be closed when there  
> are open subtasks (need to consider item 5 below and how it may  
> impact subtasks).  http://www.atlassian.com/software/jira/docs/ 
> latest/subtasks.html
>
> 4. Should we commit code when the documentation is not complete?   
> If so what time frame should be given for the documentation to be  
> completed by and how can we ensure that the documentation does not  
> end up being ignored.
>
> 5. Should we proceed with a release when there are outstanding  
> documentation tasks for items in that release?
>
> 6. Would it be beneficial to try to encourage the user community to  
> try the nightly builds from continuum to play with new features and  
> also get them more involved in reviewing and improving  
> documentation by pointing them to the list of Documentation JIRA  
> tasks for an upcoming release and encourage their feedback.
>
> 7. Would it make sense to add a field to JIRA to identify changes  
> that may have a migration impact on existing users.  This would  
> help the release manager and those reviewing a release to ensure  
> that these are all documented in the manual and the release notes  
> (possibly grouped together), as these changes have the greatest  
> potential to impact existing users.
>
> 8. Since we use JIRA for managing granular tasks during  
> development, the release notes shipped with the release may be  
> becoming of less value to users if there is a lot of items in them  
> that aren't describing a new feature or a fix.  Should we consider  
> implementing a checkbox in JIRA that determines whether the issue  
> is to be included in the release notes.  I noticed that Derby seems  
> to have implemented something like this: http://wiki.apache.org/db- 
> derby/ReleaseNoteProcess .  For example, the code change JIRA for a  
> new feature would contain a summary of the change and would have  
> the checkbox for inclusion in the release notes checked, but the  
> associated Documentation task JIRA won't have the checkbox ticked.
>
> 9. I like the outline that Derby has developed in http:// 
> wiki.apache.org/db-derby/ReleaseNoteFormat .  I am thinking we  
> should adopt that format in the description in code change JIRAs  
> for bug fixes.  Basically when a JIRA for a bug is closed, we  
> should ensure it's description follows that format.  Following this  
> format may also help communication between developers of the impact  
> of problems and their workarounds etc.
>
> Thanks,
>
> John


Mime
View raw message