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
