http://localhost/ticket/1127 <p> <strong>Proposer:</strong> Seb Bacon<br /> <strong>Seconder:</strong> Rufus Pollock<br /> <br /> </p> <h2 id="Abstract">Abstract</h2> <p> When adding new features to CKAN, a longer, more formal discussion will improve software design quality and documentation, better engage the wider community, and ensure the core team are up to date with latest developments. </p> <p> I propose a formal process (CREP -- CKAN Revision and Enhancement Proposal) for making this happen. </p> <h2 id="TheProblem">The Problem</h2> <p> The current workflow for introducing major new features into CKAN is very informal, typically based around one person's great idea, which they've discussed with one or two other people in the team. The originator of the idea is typically the only person with access to all the input they've had through such discussions. Often, the only location of this information is in that person's head. </p> <p> However, there is a lot of experience embodied in the CKAN community which should be drawn on before making large design decisions. This will lead to better software. Additionally, building consensus in the community around a proposal before implementation ensures positive community engagement and buy-in to new features, making them more likely to be a success. </p> <p> We aren't great at documenting new features. Documentation after coding is complete is an unrewarding experience for most programmers. Requiring skeleton documentation before code is written is a good discipline that can form the basis of better documentation in the future (e.g. by a writer rather than a programmer). </p> <h2 id="Specification">Specification</h2> <p> Minor features don't require a CREP, and can just be entered in the issue tracking system as a bug or feature. As a rule of thumb, a feature is major if it will take more than a day to implement, or is likely to involve matters of opinion in its design. </p> <p> If a feature requires a CREP, the proposer must first find a seconder for their idea. This sanity check step happens before a CREP is written to ensure at least the possibility of consensus on the CREP. </p> <p> Next the proposer should write a CREP, starting by copying and pasting the <a class="ext-link" href="http://wiki.ckan.net/CKAN_Revision_and_Enhancement_Proposals"><span class="icon">​</span>template on the wiki</a> into a new Trac ticket. This will be with a CREP status of "draft" and Type of "CREP.. The proposer should notify the <a class="ext-link" href="http://lists.okfn.org/mailman/listinfo/ckan-dev"><span class="icon">​</span>ckan-dev</a> mailing list, and possibly the <a class="ext-link" href="http://lists.okfn.org/mailman/listinfo/ckan-discuss"><span class="icon">​</span>ckan-discuss</a> list for less technical CREPs. </p> <p> The draft can be discussed via email, verbally, or via the trac ticket. In any case, it is the proposer's responsibility to keep the CREP updated to reflect the current consensus. </p> <p> Once consensus has been reached, the ticket should be marked as "accepted" status and assigned to a CKAN release milestone. </p> <p> When an accepted CREP has been implemented, it should be marked as "completed". </p> <p> If no consensus can be reached on a draft CREP, or for some reason an accepted CREP doesn't get completed, it should be marked as "rejected". </p> <p> If a completed CREP becomes obselete, it should be marked as "obselete". </p> <h2 id="Whydoitthisway">Why do it this way</h2> <p> Given the distributed nature of the core team plus other volunteers, some kind of written procedure is necessary to ensure a fully documented and discussed proposal. </p> <p> The idea of "Enhancement Proposals" which can be semi-formally proposed and discussed prior to implementation is common in the Open Source world (<a class="ext-link" href="http://www.python.org/dev/peps/pep-0001/"><span class="icon">​</span>PEPs</a>, <a class="ext-link" href="http://dep.debian.net/"><span class="icon">​</span>DEPs</a>, <a class="ext-link" href="http://plone.org/documentation/glossary/plip"><span class="icon">​</span>PLIPs</a>, to name three). </p> <p> Existing historic proposals exist, called CEPs. The proposed system is called CREP (CKAN revision or enhancement proposal) to disambiguate it from the legacy proposals, and from the delicious fungus <em>Boletus Edulis</em>. </p> <p> Giving a formal structure to the proposal is useful as it gives the community a means to identify a CREP that's not had sufficient thought or discussion. An informal email thread can easily be lost and important questions (such as backwards compatibility) overlooked. The use of the proposed template empowers any community member to ask the proposer to expand on rationale, deliverables, etc. </p> <p> The structure chosen is somewhere between Debian's and Plone's. It aims to give a structure to the debate, a clear start at documentation, and also prompt some thinking about implementation and timescales. </p> <p> Some projects (e.g. Debian) keep their enhancement proposals in a versioning repository; others (e.g. Plone) keep them in an issue tracking system. Trac is proposed for CKAN because we already use it for small feature proposals and for team planning. It seems unlikely that change tracking on an individual CREP will be useful; a CREP that changes sufficiently from its original form should probably be marked "obselete" and a new CREP started. Using an issue tracking system also means we can easily track CREPs by state. </p> <h2 id="BackwardsCompatibility">Backwards Compatibility</h2> <p> Some <a class="ext-link" href="https://bitbucket.org/okfn/ceps/src/76b274888bcf/cep/"><span class="icon">​</span>legacy enhancement proposals</a>, called CEPs, have previously been started. </p> <p> They are currently all marked as "active". Any which require discussion should be altered by the proposer to match the new CREP specification and submitted to trac. The original CEP should be updated with a banner at the top pointing a reader to the new CREP. </p> <p> Any that are now obselete should be clearly marked as such in a banner at the top, pointing a reader to the trac for new CREPs. </p> <h2 id="Implementationplan">Implementation plan</h2> <h3 id="Deliverables">Deliverables</h3> <ul><li>This CREP, agreed </li><li>Support for proposed statuses in Trac </li><li>Canned reports for listing CREPs in Trac </li></ul><h3 id="Risksandmitigations">Risks and mitigations</h3> <ul><li>That this CREP is agreed, but rarely acted on. This risk can be mitigated by nominating a CREP champion in the community or core team, whose job it is to say "where's the CREP for that?" and generally own the quality of CREPS </li></ul><h3 id="Participants">Participants</h3> <p> Once agreed, we need a CREP champion -- as yet unassigned </p> <h3 id="Progress">Progress</h3> <p> This document is the entire proposal. </p> en-us http://assets.okfn.org/p/ckan/img/ckan_logo_shortname.png http://localhost/ticket/1127 Trac 0.12.3 sebbacon Thu, 05 May 2011 13:15:40 GMT http://localhost/ticket/1127#comment:1 http://localhost/ticket/1127#comment:1 <ul> <li><strong>summary</strong> changed from <em>Formalise new feature discussion and definition using CREPs</em> to <em>CREP0001: Formalise new feature discussion and definition using CREPs</em> </li> </ul> Ticket wwaites Thu, 05 May 2011 13:28:04 GMT http://localhost/ticket/1127#comment:2 http://localhost/ticket/1127#comment:2 <p> The proposal is not comparable to PEP and DEP because the projects have vastly different requirements. The API stability needs of a programming language or an operating system (e.g. fundamental building blocks that you don't expect to change often or radically) are very different from a web application. The plone one is comparable. </p> <p> The idea itself is a double-edged sword. It will promote stability which is good but can also tend towards rigidity and stagnation which is bad. Each added bit of bureaucracy and process means fewer people will be willing to collaborate or participate in improving the software. </p> <p> Overall, -1. </p> Ticket dread Thu, 05 May 2011 14:34:54 GMT http://localhost/ticket/1127#comment:3 http://localhost/ticket/1127#comment:3 <ul> <li><strong>description</strong> modified (<a href="/ticket/1127?action=diff&amp;version=3">diff</a>) </li> </ul> <p> Fixed links </p> Ticket thejimmyg Wed, 11 May 2011 15:33:20 GMT http://localhost/ticket/1127#comment:4 http://localhost/ticket/1127#comment:4 <p> This is great idea and it has taken on well. +1 from me. We can update/create new CREP policies as needed. </p> Ticket rgrp Sun, 15 May 2011 11:13:40 GMT http://localhost/ticket/1127#comment:5 http://localhost/ticket/1127#comment:5 <p> I'm obviously a strong +1 but feel we should stick with the CEP name (we have PEP and DEP and CREP really does sound weird compared to CEP). </p> <p> Also I think we may need to do a bit more to clarify when you just do a good ticket and when one does a CEP (looking at what has occurred already). I think this may be one reason to keep CEPs separate in drafting from trac as will clearly distinguish CEPs from standard tickets. </p> Ticket rgrp Sun, 15 May 2011 11:21:29 GMT http://localhost/ticket/1127#comment:6 http://localhost/ticket/1127#comment:6 <p> one other thing: i think the plan is for CEPs to be in restructured text (for easy transfer to docs). This should be mentioned and the template in the wiki should be in ReST. </p> Ticket sebbacon Tue, 17 May 2011 09:00:50 GMT http://localhost/ticket/1127#comment:7 http://localhost/ticket/1127#comment:7 <ul> <li><strong>status</strong> changed from <em>new</em> to <em>closed</em> </li> <li><strong>resolution</strong> set to <em>fixed</em> </li> <li><strong>description</strong> modified (<a href="/ticket/1127?action=diff&amp;version=7">diff</a>) </li> </ul> Ticket