View source for Project policy

{{policy}}

The '''Project Policy''' describes  how members of the community propose to make changes in MIT Kerberos.  A project is a proposal to add new functionality or to change existing functionality in MIT Kerberos.  Projects are reviewed by the community before  the required changes can be integrated into MIT Kerberos.  This review provides the community an opportunity to suggest improvements to the project and to confirm that the community believes that  implementing the project would be a good idea.

==When are projects needed?==

Small changes and relatively simple bug fixes do not require a project.   The project process is designed to provide sufficient community review.  If a change is simple enough and uncontroversial enough  then the change can be made without going through this process.  If members of the development community,especially members of [[Krbcore]], wish to review the change then it should go through a project process.  If a change is committed outside of a project and objections are raised, then any member of Krbcore may revert the change until a project is approved.

The following always require  the project process to be invoked:
# Introduction of any public [[API]]s
# Changes in an API or the [[ABI]].  Such changes are rarely approved
# Significant user interface changes such as the introduction of a new dialogue .
# Introduction of configuration file variables or documented registry keys

==Proposing  a project==

To propose a project, create a new page under [[Projects]].  For example a project to create a new administration protocol might be called "Projects/new administration protocol". 
At the beginning of that page include the following:
<blockquote>
<nowiki>{{project-early}}
</nowiki></blockquote>
This will include the [[Template:project-early|early project template]] which indicates that the project is being fleshed out by its supporters and is not yet under consideration for approval.  Note, to create a page enter the page name ("Projects/new administration protocol" for example) in the wiki search box on left and click on the Go button.

The completed project proposal page should include the following elements:
* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the  desired functionality will be implemented
* A breakdown of tasks  or milestones to judge  progress of the project
* Screenshots or other proposed user interface  descriptions
* Documentation and sample  code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

You do not need to fully describe each of the above elements prior to seeking community input.  If you wish, you may solicit the krbdev mailing list (or smaller groups of developers) to look at the proposal to provide feedback.  This allows you to iteratively improve your project proposal to the point where it is ready for formal review.

===User Interface===

It is expected that screenshots describing any proposed user interface will be included in any project that describes new interfaces.  Discussion of customer study groups that have evaluated the new interface or other information to validate the interface will help support the project.

===Documenting proposed APIs===
See [[Documenting APIs]] for current recommendations on how to document APIs that are introduced in a project.  Typically, the community will expect sample code to be included describing the use of APIs that are introduced.

==Which release does a project go in==

Unless a project mentions it is targeting a specific release, then the project will be included in the next release [[Release branches|branched]] off the [[trunk]] after the project is checked in.

Typically the goals of a given release are set during a release planning process at the beginning of that release process.  It is unusual to include additional projects in a release   after the planning has concluded.   A project may propose that it be included in a specific release after the goals for that release have been set, although absent a very convincing justification this is likely to result in blocking objections.

If a project is a goal for a given release, it will typically need to include milestones  to judge its progress against the rest of the release.  If the project is being managed by the consortium staff,  then the consortium project tracking process will be used.    For projects not being done by consortium staff, it is typical to establish coordination point milestones.  See [[Meeting release goals]] for information on how these milestones are used once projects are approved.


==Submitting a project for review==

Except in cases where prompt action is required, projects require a two week review cycle.  Projects require at least one  yes vote from a member of Krbcore  who has not been a primary proponent of the project to be approved and no blocking objections.    Proponents of the project should work  with members of the community to address suggestions that are raised even if these suggestions are not blocking objections.   If discussion of significant issues is ongoing when the review period extends then approval should be delayed until the discussion concludes.


To start the review period :
# Replace <nowiki>{{project-early}} with {{project-review|end_of_review_date}}</nowiki>
# Add <nowiki>{{subst:project-vote}}</nowiki> at the bottom of the project page.
# Send mail  to krbdev@mit.edu announcing the review period.  The <nowiki>{{project-review}}</nowiki> template will claim that mail has been sent; the template has no way of knowing whether the mail actually has been sent, and it is the responsibility of the party adding the template to actually send this mail.  The mail should include:
##The URI to the project page
##The end of the review period
##Cut and paste the description of the project from the project page.

==That's a good start==

Often the result of a review will be that what is written so far is good enough that the community wants to explore the project, but checkpoints or '''review gates''' are required.  Examples of such gates include things like  requesting review of design of a particular part of the system, requesting review of APIs that are designed in the future, or interactions with  some part of the system.  Particularly when some of the recommended information is not included in the original project proposal, a review gate may be requested.  When the information to be reviewed is available, another project review should be conducted.  There are no specific details on how to  document this review other than that the <nowiki>{{project-review}}</nowiki> template should be used so that the project is categorized as under review.

== Project life cycle changes==

===Approving a project===

If the project review concludes successfully  then:
# Replace <nowiki>{{project-review}} with {{project-approved}}</nowiki>.
#Add a ''Current status'' section at the bottom of the project page to track updates
# Send mail to krbdev@mit.edu noting that the project is approved.
# If the project is targeted for a specific release add <nowiki>{{project-target|release_name}}</nowiki> below the project-approved target.

===Marking a project as completed===

Replace <nowiki>{{project-approved}}</nowiki> with <nowiki>{{project-completed}}</nowiki>.  If the release including the project has shipped, replace <nowiki>{{project-target}} with {{project-release|release_name}}</nowiki>

===Updating the scope or design of the project===

Any significant updates to the project design or scope should be sent to krbdev@mit.edu.    Comments should be addressed; if blocking objections are raised  then they must be addressed.