On Mon, 10 Jan 2011, Robert Godfrey wrote:
Hi, Rob.
Hi Justin,
On 6 January 2011 15:42, Justin Ross <[email protected]> wrote:
Hi, everyone.
I'd like to propose a new way to communicate about the major changes going
into our releases. The goal is to help us make decisions early in the
process, coordinate when a change in one place impacts another, and engender
a broader sense of direction. It should also help to document the work that
we do.
So, I have a few questions / comments about this.
Firstly I think we need to be clear whether QIPs are describing an end state
(an implied specification), or the act of making the change to the codebase
to achieve the end result (which is what a JIRA is for - surely)?.
QIPs are mostly end-state oriented, but they may include notes about
implementation insofar as they help us understand a features impact on a
release.
Secondly, I think we need to have a better definition of when a change
should be a QIP or not: what constitutes "major"? does a purely internal
refactoring count? what about removing an unloved component?
I'm not entirely decided on what the criteria should be, and I'm not yet
convinced they need to be strict. We can always look at an incoming
change and say, "that seems big, please submit a QIP".
To my sensibilities, an internal refactoring would not call for a QIP.
Removing an unloved component might, depending on impact. I can imagine a
case where the developers hate component X and want to remove it, but the
users like it. In that case, we could use the higher-level release
decision making that QIPs require.
Next I think we need to understand better how QIPs would relate to JIRAs.
I'm firmly of the opinion that nothing should be getting in to the codebase
without a JIRA that explains the reason for the change. That doesn't
necessarily remove the need for a system for recording proposals to change
the "definition" of Qpid... but if I had to chose either a "proposals"
system or a change/defect tracker, I'd choose the latter.
Eeeks! I definitely don't wish to propose we have one or the other. More
on this below.
I certainly see a lot of value in tracking "proposals" separately to actual
work tasks (which is what we predominantly have in JIRA right now). However
I think it is work tasks that make up a release, so it is those (rather than
QIPs) which would be scheduled and tracked. I'm less sure about using svn
as tool for storing in-process QIPs - it seems unnatural. Using a wiki or a
workflow (such as JIRA the tool rather than our current instance of it)
I'm pretty indifferent on the question of where draft QIPs should go. I
do, however, think of QIPs as documentation, so once accepted I tend to
think they should go next to our other project documentation at qpid/doc.
seems more obvious. There is utility in capturing completed QIPs as part of
our documentation if they define an interface or feature that is to be
exposed to our users (or possibly define why a specific feature or interface
has not been defined (or has been removed)). Wiki and JIRA both preserve a
similar level of source control and history to svn.
To do this, I've imitated an approach that's been used in other community
software projects. The Python project, for instance, uses Python
Enhancement Proposals (PEPs) to review important changes to the Python
language [1].
I've attempted to produce something very similar here and tie it into our
release process. It's my hope that during the 0.10 cycle some contributors
will opt to describe their major changes using the QIP process. This is,
however, entirely optional.
As above, I'm not sure that QIPs should be what releases are based on. If a
given QIP can be broken into two (or more) discrete pieces of work which can
then be defined as JIRAs, then it would seem to me that at the point the
release was being cute, then it could be OK (depending on the precise
details of the changes) for it to go out with only some, but not all, of the
JIRAs completed.
It depends on what you mean by "what releases are based on". I am
explicitly proposing that at some point in the future, we the community
use QIP review to signal the acceptance or rejection of major work early
in a release cycle.
On the tail end, however, I agree. When we are nearing the end of a
release, I'm all in favor of triaging the JIRAs in favor of a discipined,
regular release schedule (with no inadvertent regressions).
The attached QIP 1 and QIP template should provide an overview of how this
might work. This is very much in an early and unrefined form, so I hope
you'll take a look and share your thoughts.
As a group I think we need to do a lot more work on trying to define our
goals (whether for an individual release, or more generally in terms of what
we are trying to make Qpid be). And we need to be much better at
understanding how each release is getting us closer to our goal.
As an example, what is it that we are trying to achieve in our next (0.10)
release? And how will it help our end users?
It is against these goals that I think QIPs need to be evaluated. I think
the process of planning release priorities may be in terms of QIPs, but more
likely in terms of a mix of QIPS and JIRAs... and every piece of work should
have a JIRA for it before it gets checked in. If we use the JIRA system
properly we can get a much better overview of the state of the trunk and
(eventually) the release itself.
I don't intend for QIPs to replace JIRAs.
Much like you've outlined it here, a QIP is specification-focused, and a
JIRA is implementation-focused. An accepted QIP becomes a permanent part
of Qpid project history and documentation, while a JIRA typically gets
closed and forgotten.
I anticipate a single QIP, once accepted, producing a bunch of JIRAs for
the underlying work.
A QIP may include notes about the implementation, but that's simply to
serve the goal of integration: we need to decide we want a feature
and--just as much--we need to decide whether it's practical to take it in
a given release.
(As an aside, I'm not sure "Qpid Improvement Process" is a good name to give
these things, they seem more like proposals and an "Improvement Proposal"
still seems more like a task - i.e. a JIRA... )
Indeed, QIP does stand for Qpid Improvement Proposal (see QIP 1). I
titled QIP 1 and this email thread "Qpid Improvement Process" because QIPs
by themselves are just form-style documents. The attendant process of
reviewing and approving them in a release-coordinated way is just as
important.
Also, to my ear "improvement" does not imply task. The advantage of it
(as with "enhancement" from the Python and Gnome variants) is that it
captures a very broad category of major change: new feature, new api,
new website, new community process.
As you've pointed out, however, a lot more detail is needed on the process
side. Thanks to you and others who have shared their comments, I hope to
have the needed clarity soon.
Thanks,
Justin
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
