You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geronimo.apache.org by John Sisson <jr...@gmail.com> on 2006/07/01 03:56:16 UTC
[DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification
please from the PMC )
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
Re: [DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification please from the PMC )
Posted by Jason Dillon <ja...@planet57.com>.
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
Re: [DISCUSS] Tracking documentation tasks in JIRA ( was Re: [RTC] Clarification please from the PMC )
Posted by Jason Dillon <ja...@planet57.com>.
> 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.
I agree that JIRA should track the relevant details. Sometimes those
details are discussed in IRC. When that happens I recommend that the
relevant snips of the chat be added to the related issues as comments.
> 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
> 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:
Mixed feelings about this...
I think that its good to have more visibility/oversight on
documentation and how it relates to code changes...
But I think that this might be a bit much.
I'd rather see that the code change JIRA have enough description or
comments to be used as the basis for new documentation and explain
the details of the change for release notes. And for major changes
have a per-release page in the wiki to track more human readable
notes perhaps with references to issues or other detail pages.
I really like how Atlassian tracks their notes with Confluence and
use the {jiraissues} macro to include JIRA issues in the detail pages:
http://confluence.atlassian.com/display/DOC/Release+Notes
I'd recommend following this style for release notes. I setup a
similar policy at the last company I was at and it worked out quite
well for about 5 different groups working on about 12 different
projects.
Anyways, I like the idea of more documentation oversight... but
concerned that we try and keep it simple. IMO adding a new
documentation issue seems to add significant complexity and overhead,
which may end up degrading the overall flow of documentation.
--jason