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
