geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From John Sisson <>
Subject [DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification please from the PMC )
Date Sat, 01 Jul 2006 01:56:16 GMT
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. 


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 

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: .  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 .  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.



View raw message