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