what i came to pull together the material for the proposal template, i found
that it didn't really fit into the annotation template format originally
conceived. so, here is a first draft of a guide for proposals containing a
template. it's rough and ready but the polish can be applied later.
the heraldry proposal works quite well for me so the format is a little
closer to the less structured format than the original discussion. i think
that this is good since it produces better prose and less box ticking. those
who have objections to this less structure approach should probably jump in
here (rather than in line).
comments in line, please. it's a long post so please cut everything which is
not relevant to the comment.
- robert
Guide For Proposal Creation
=====================
Abstract
------------
This document is descriptive not normative. It describes ways to go about
drawing up a proposal for submission. It is not an inflexible standard but
does respresent a consensus condensed from previous discussions on the
incubator general list.
Background
-----------------
Entry to the incubator is a democractic process. The incubator pmc votes on
whether to accept or not. The proposal is the document upon which the pmc
votes. So, though it's not necessary or sufficient to have a good proposal,
a good proposal document will increase the chances of a positive result.
The proposal is (in some ways) a manifesto. It should shape the evolution of
the product at apache. A lot of the information contained should be included
in the initial project website.
Help Wanted!
-------------------
Help to improve the system by posting patching for this document to the
incubator section of JIRA.
Formulating A Proposal
=================
Start by RTFM. The Entry To The incubator is a good place to start this
process.
Spend some time reviewing the mailing lists and subscribe to
[EMAIL PROTECTED] The mailing lists are the canonical form of
communication and
decision making at apache. The documentation represents an attempt to codify
the consensus formed on list.
Before drawing up a lengthy proposal, recruit a champion. [links to other
documentation explaning role of champion] The champion knows how apache work
and should be able to navigate the process.
Review recent proposals [links to the wiki] and how they have been received.
The incoming community needs to work together before presenting this
proposal to
the incubator. Think about goals and about the reasons for coming to apache.
Once the preparatory work is done, the proposal should be presented to the
incubator. This is done by posting the proposal
in plain text in a email whose subject is prefixed with [PROPOSAL].
Expect to work on improving the template on list after presenting it. The
wiki is an excellent way to develop a proposal so consider creating a wiki
page containing the same content and supplying a link. Interested parties
may wish to add themselves to the watch list for the page so that received
email notifications
when the page is changed.
When the proposal seems finish and some sort of consensus has emerged, the
proposal can be put to the vote.
Proposal Template
==============
The aim of presenting a template with examples and comments is educational.
Proposals are not required to adopt this format. If you can see a better
way: great.
Every proposal is different. There may be sections which don't seem to be
useful. It's fine to miss them out and add new ones that the proposal seems
to need.
Abstract
------------
<commentary>
What is the proposed project? This is a short descriptive summary of the
project. Ideally one sentence in length.
It is important that the technical vision for an open source project can be
communicated in a short paragraph. This paragraph will most like be used for
the board resolution used to create the official project upon graduation,
may be used as the first paragraph on the web site and as the DOAP
description.
</commentary>
Examples:
Geronimo will be a J2EE compliant container.
Heraldry will develop technologies around the emerging user-centric
identity space.
Yoko will be a CORBA server.
Proposal
-------------
<commentary>
A lengthier description of the proposal. Should be reasonably declarative.
More discursive material can be included in later sections.
</commentary>
Background
-----------------
<commentary>
For some projects, it may be useful to provide context. If you proposal
contains words that for which there is not a consensus definition, please
explain what you mean by them. if the problem domain is likely to be
unfamiliar to many then please outline the domain.
This content should be capable of being safely ignored by any domain
experts.
This material should probably find an eventual home on the project website.
</commentary>
Rationale
-------------
<commentary>
Why does this project need to exist and why should it be adopted by apache?
More discursive material is probably better in this section rather than in
the proposal.
This content should be ignorable for those for whom the need is obvious.
</commentary>
Initial Goals
-----------------
<commentary>
Only include this section if it is not obvious. If the proposal is complex
(probably involving multiple code bases) then people may worry about it's
practicallity and whether it may drag in too much apache energy to make it
happen.
This is a good place to explain the plan and demonstrate that the proposal
is feasible and has been thought through.
</commentary>
Example (heraldry)
* Expansion of Yadis and OpenID libraries into additional
languages beyond the existing Python, Ruby, Perl, and PHP libraries
* OpenID authentication specification revision to fix known
security considerations, investigate compatibility with the DIX IETF
proposal, describe Yadis integration, and allow either an URL or XRI be used
as the End User's Identifier
* Continue the development of a data transfer protocol on top of
OpenID to allow the exchange of profile data as well as other secure
messages
* Investigate existing mechanisms for profile exchange, namely
Sxip 2.0 and SAML, and investigate how they would be layered atop OpenID
* Integration of the OpenID Authentication protocol with the
Higgins framework to provide desktop integration
* Extension of OpenID to support non-browser based
authentication use cases. ie authentication to a Subversion server, creation
of mod_authnz_openid, using your OpenID Identity without modifying the svn
client-side tool
Current Status
---------------------
<commentary>
It is sometimes useful for proposal around existing projects to compare
where they are know against principles and ideals. A few topics:
* Meritocracy
* Community
* Core Developers
* Alignment
[need more content describing these attributes]
Some proposals describe this section as criteria.
</commentary>
Known Risks
-------------------
<commentary>
An exercise in self-knowledge.
Risks don't mean that a project is unacceptable.
It is useful to collect together material to prempt questions about possible
risks.
Not all projects will need to address all points.
Some possible topics:
* Orphaned products
[needs improvements?] This is the right place for the
proposers to publically state their commitment to future development. It
takes quite a while to recruit a diverse development community. So Apache
needs to be confident that those already working on the product are still
committed.
example:
(YOKO) "The contributors are leading vendors in this space.
There is no risk of any of the usual warning signs of orphaned or abandoned
code."
* Inexperience with open source
[needs improvements?] One of the reasons why many closed
project choose to move to here is the experience of Apache in the open
source space. But this means an invest of energy by Apache so many people
look for a willingness to learn and to give back to the community.
* Homogenous developers -
[needs improvements?] Healthy projects need a mix of
developers. Open development means a commitment to encouraging a diverse mix
of developers.
* Reliance on salaried developers
[needs improvements?] People worry about salaried developers
who are interested in working on this project only whilst they are employed
to do so.
* Relationships with other Apache products
[needs improvements?]
People are concerned about projects that work just inside
their own little bubble. Apache encourages projects to open to collaboration
with other open source projects both within apache and without. This may be
existing links but is also a good place to talk about potential future links
and plans.
Apache allows different projects to have competing or
overlapping goals. However, this should mean friendly competition with
coorporation whenever this makes sense. It is not always obvious to all
whether the proposers see themselves as direct competitors with an existing
project, indirect competitors (same problem space, different ecological
niche) or just peers with some overlap. In the case of indirect competition,
it may be important that the abstract describe accurately the niche.
* A fascination with the Apache brand
[needs improvements?] Concerns have been raised in the past
that some projects are proposed just to generate positive publicity for
themselves. This is a chance to build bridges with the community after past
misdemeanors (for example, if any of those associated with the proposal have
- in the past - sort to associate themselves with the Apache brand in
factually incorrect ways) and promise good conduct for the future.
</commentary>
Documentation
----------------------
<commentary>
References to further reading material
</commentary>
Initial Source
-------------------
<commentary>
Describes where the proposed code base comes from.
</commentary>
Source and Intellectual Property Submission Plan
------------------------------------------------------------------------
<commentary>
More complex proposals (typically involving mutliple code bases) may prefer
to draw up an initial plan for the submission of the code in a separate
section. Demonstrates that the proposal is practical.
</commentary>
External Dependencies
---------------------------------
<commentary>
External dependencies for the initial source is important. Apache has policy
about dependencies allowed for projects. These are (to some extent) relaxed
for projects under incubation. Listing dependencies and licenses allows any
possible problems to be highlighted and the appropriate actions planned.
</commentary>
Cryptography
-------------------
<commentary>
If the proposal involves cryptographic code either directly or indirectly,
Apache needs to know so that the relevant export documentation can be
obtained.
</commentary>
Required Resources
-----------------------------
<commentary>
Create a list of resources that the Apache infrastructure will
supply for this project.
* Mailing lists
Minimum project-private (for pmc) project-dev listing
It is often best to start with these minimum lists. The initial
focus should be recruiting new developers. Developers need to get into the
habit of reading and checking commit messages. As momentum is gained, the
community may decide that to create commit and user lists in the usual way.
However, existing open source projects with active user lists
may need to start with separate lists from the start.
* subversion directory
* issue tracking
This means choosing either JIRA or Bugzilla.
Other resources such as continuous integration and so on should be
added by the podling later in the usual way as momentum is gained.
If the proposal requires other special infrastructure, it is best to
give an explaination. The Apache infrastructure team usually takes some
convincing before allowing new services on Apache hardware
</commentary>
Initial Committers
-------------------------
<commentary>
List of committers used to bootstrap the community. Note which have
submitted CLAs.
It is a good idea to submit CLAs at the same time as proposal and
before acceptance. There is nothing lost by having a CLA on file at Apache
but they do take some time to process.
</commentary>
Affiliations
---------------
<commentary>
Little bit of a controversial subject. Committers at apache are individuals
and work here on their own behalf and are judged on their merits not their
affiliations. However, it is useful (in the spirit of full disclosure) for
any current affiliations which may effect their independence to be listed.
For example, those in a salaried positions whose job is to work on the
project should list their affiliation. Having this list helps to judge how
much diversity exists in the initial list and so how much work there is to
do.
It's probably best to do this in a separate section away from the committers
list.
</commentary>
Sponsors
-------------
Champion
<commentary>
[needs improvements?] A champion should be found before the proposal is
submitted.
</commentary>
Mentors
<commentary>
[needs improvements?]
The list of mentors may well be established during development
of the proposal. The absolute minimum is a single mentor but the current
consensus is that (at least) three mentors will make things go more
smoothly. Three mentors gives a quorum and allows the project more autonomy.
The number of mentors a podling can have is limited only by the
energy and interest of those eligable to mentor.
</commentary>
Sponsoring Entitry
<commentary>
This is the organisational unit within Apache taking resposibility for this
proposal.
The sponsoring entity can be:
the board
another Apache project
the incubator pmc
Unless there are strong links to an existing pmc, it is recommended that the
proposal asked that the incubator pmc to act as sponsor.
Note that the final destination within the Apache organisational structure
will be decided upon graduation.
</commentary>
