Difference between revisions of "Project policy"

Revision as of 15:29, 4 October 2012

This page represents an official policy of the MIT Kerberos project. Edit this page only in accordance with changes agreed by the community; other changes will be reverted.

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:

1. Introduction of any public APIs
2. Changes in an API or the ABI. Such changes are rarely approved
3. Significant user interface changes such as the introduction of a new dialogue .
4. 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:

{{project-early}}

This will include the 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 branched off the Master branch 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 :

1. Replace {{project-early}} with {{project-review|end_of_review_date}}
2. Add {{subst:project-vote}} at the bottom of the project page.
3. Send mail to krbdev@mit.edu announcing the review period. The {{project-review}} 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:
   1. The URI to the project page
   2. The end of the review period
   3. 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 {{project-review}} 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:

1. Replace {{project-review}} with {{project-approved}}.
2. Add a Current status section at the bottom of the project page to track updates
3. Send mail to krbdev@mit.edu noting that the project is approved.
4. If the project is targeted for a specific release add {{project-target|release_name}} below the project-approved target.

Marking a project as completed

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

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.