incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "robert burrell donkin" <robertburrelldon...@gmail.com>
Subject Re: [documentation][DRAFT] Proposal Guide
Date Tue, 11 Jul 2006 11:53:07 GMT
On 7/5/06, robert burrell donkin <robertburrelldonkin@gmail.com> wrote:
>
> 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.
>

anyone have any improvements or comments?

(otherwise i'll commit something similar in the next day or two)

- 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
> general@incubator.apache.org. 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>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message