source/chapters/release.adoc

////
 * Copyright (C) 2015 Eclipse Foundation, Inc. and others. 
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-License-Identifier: EPL-2.0
////

[[release]]
== Releases

Releases are formal for {forgeName} projects. 

Releases are broadly categorized as:

* _Major_ releases include API changes (potential for downstream breakage);
* _Minor_ releases add new functionality, but are API compatible with previous versions; and
* _Service_ releases include bug fixes only and include no significant new functionality.

For many {forgeName} projects, the release lifecycle follows the traditional pattern of every release being preceded by a release review. This is especially true for projects with release cycles that span a year or more.

[graphviz, images/release-cycle, svg]
.The Release Cycle
----
include::diagrams/edp_release_lifecycle.dot[]
----

Every release cycle starts with a <<releases-plan, plan>> that is created in an open and transparent manner and made available the community both for review and to solicit input. The development process must be iterative, with the regular delivery of <<release-milestones, milestone builds>> to solicit feedback. The release cycle ends with the delivery of a final release candidate, a <<release-review, release review>>, and general availability of the products of the release.

A project team may declare official major or minor releases and distribute associated products for up to one year following a successful _<<release-review,release or progress review>>_. Reviews are not required for bug-fix/service releases.

[[NOTE]]
====
*Intellectual property must be properly accounted for and tracked at all times.* The project team must engage in the Eclipse IP Due Diligence Process on an ongoing basis. The IP Log review and approval that occurs at the time of either a release review or progress review should be regarded as a means of confirming that intellectual property is being properly managed and not as a trigger to engage in a last minute clean up.

All tracking of project and third-party content must be current and correct at all times.
====

[[releases-plan]]
=== Release Plan

A project plan is _required_ for each major and minor project release. The plan should lay out in broad terms what the goals are for the release. As plans are a valuable means for the community to get involved with your project, the plan should be created at the beginning of the release cycle. By establishing the plan early, you give prospective contributors help in determining how they can most usefully contribute, and adopters can prepare their own development schedule and themes. Plans can change during the release cycle.

Release records are used to capture a project plan. All project leads and committers can use the <<pmi-commands-release, Create a new release>> command on their <<pmi-project-page, project page>> in the <<pmi,Project Management Interface (PMI)>> to create a new release record.

At the start of the release cycle, a plan should minimally include a release number, date, and short description. All aspects of a plan can change during the release cycle (including the date). If you do change the plan, make sure that the change is communicated via your project's _dev-list_ and other project channels.

[TIP]
====
Think of the description of the project plan as an _elevator pitch_: how would you describe the release in a fifteen second elevator ride? 
====

The _Plan_ tab in the release record contains numerous fields for capturing plan information. The amount of information that you should capture for a release plan varies by top-level project, so consult with your Project Management Committee (PMC) for advice.

Producing regular builds is an important part of the release cycle. Builds are an important means of engaging with the community: adopters can help you test your code and test their own so that they can be ready for the eventual release. Project teams should plan to produce at least one _milestone_ build (more are better, depending on the length of your release cycle), and capture the planned date for that milestone in the release record. It is also common practice to generate nightly and weekly integration builds. Project teams must ensure that their project's downloads page provides the information required for the community to obtain builds.

All requests for review of <<ip,intellectual property>> contributions must be approved by the IP Team before the products of a release are pushed out onto distribution channels (this includes third-party content and contributions of code to be maintained by the project).

[[release-milestones]]
=== Milestones and Release Candidates

Milestone builds and release candidates are not themselves official releases. Per the {edpLink}, milestone and release candidate builds are intended to be consumed by a limited audience to solicit, gather, and incorporate feedback from leading edge consumers. A predictable schedule for the delivery of milestone builds is especially valuable when the period of time between formal releases spans multiple months. 

Project teams should include at least one milestone build during every release cycle. The timing of milestone and release candidate builds should be included in release plans.

[[release-review]]
=== Progress and Release Reviews

Progress and release reviews differ only in timing. A progress review can be scheduled at any point in a project's release cycle; a release review is scheduled at the end of the release cycle. A _release review_ can be thought of as a formal announcement of a release to the community. 

These reviews generally serve as a means for a project to engage in a retrospective of the progress made during the release, discover areas of potential improvement, demonstrate that the project is operating in an open and transparent manner, and ensure that the development process and intellectual due diligence processes have been followed.

Reviews run for a week and always conclude on a Wednesday. 

[NOTE]
====
We schedule reviews to conclude on the _first and third Wednesdays of the month_. Your release date does not have to  coincide with the review date (you can set the release date as necessary). The review must, however, conclude successfully before you can make the release official.
====

_Release and progress reviews_ require review documentation and an intellectual property (IP) log check. The review process must be initiated at least two weeks in advance of the anticipated review date.

[graphviz, images/release-review, svg]
.Release review work flow
----
digraph {
	// Graph properties
	bgcolor=transparent
	
	// Nodes that define the key points in the process
	node [shape=box;style=filled;fillcolor=white;fontsize=12;width=2]
	doc [label="Review\nDocumentation", group=g1]
	pmc [label="PMC\nApproval", group=g1]
	ipteam [label="IP Log Approval\n(IP Team)", group=g2]
	start [label="Start\Review", group=g3]
	end [label="End\nRelease Review", group=g3]
	publish [label="Publish Release", group=g3]
	
	doc -> start
	pmc -> start
	ipteam -> start
	start -> end -> publish
}
----

The project team must prepare the review documentation well in advance of the start of the review period. See this <<checklist,checklist>> used as part of evaluation during a Release Review. The release record which contains the project plan also includes a _Review_ tab with appropriate fields for a review. As with the plan fields, all of the review fields are optional and the level of detail required varies by top-level project. Project teams can assemble review information during the release cycle (there's no need to wait until the end)

The review materials must be approved by the PMC; the project lead or a designated project committer should send an email to the PMC's mailing list with a request for approval. The PMC will respond with feedback or a simple `pass:[+1]` indicating approval.

[TIP]
====
Click the handy menu:Committer Tools[Communication > Send Email to the PMC] link on the release record page to connect with the PMC.
====

The IP Team must approve the IP Log before the EMO can schedule the review, so submitting this early is important. The <<ip-iplog-generator,IP Log generator>> automatically collects information based on the information that the project team has provided to the IP Team through <<ip-cq,contribution questionnaires>> in IPZilla, commits in the project's source code repository, and other information in our databases. The project team should review the IP Log before submitting to the IP Team for their review.

[TIP]
====
Use the <<pmi-commands-iplog, Generate IP Log>> tool on a specific <<pmi-project-page, project page>> in the <<pmi,Project Management Interface (PMI)>> to generate and submit the IP Log for review.
====

The information used to generate an IP Log should always be up-to-date (don't wait until the end of the release cycle to make it right).

At any point in this process, the project lead or a designated committer can request that the review be initiated by clicking the menu:Schedule a review for this release[] link that appears at the top of the release record page.

[NOTE]
====
The EMO will likely notice that you've created the release record, connected with your PMC, and submitted an IP Log for review by the IP team and will take steps to initiate the actual review. However, since there is a great deal of variability in this process, send an email to mailto:{emoEmail}[EMO] stating your intent to release.
====

The EMO will conclude the review on the scheduled end date and advise the project team of the outcome.

[[release-graduation]]
=== Graduation Reviews

The purpose of a _graduation review_ is to confirm that the project has a working and demonstrable code base of sufficiently high quality active and sufficiently diverse communities; has adopters, developers, and users operating fully in the open following the {edpLink}; and is a credit to {forgeName} and is functioning well within the larger {forgeName} community

Graduation reviews are generally combined with a _<<release-review, release review>>_ (typically, but not necessarily the `1.0` release). Upon successful completion of a graduation review, a project will leave the incubation phase and be designated as a _mature_ project.

For a graduation review, release review documentation must be augmented to include demonstration of:

* solid working code with stable APIs; 
* an established and growing community around the project;
* diverse multi-organization committer/contributor/developer activity; and
* operation in the open using open source rules of engagement.

The graduation review documentation should demonstrate that members have learned the ropes and logistics of being {aForgeName} project. That is, the project "gets the {forgeName} way".

[[release-faq]]
=== Frequently Asked Questions

[qanda]
Can a release review fail? ::

Technically, yes. A release review can fail. In our history, however, this occurrs very rarely. We set up release reviews to succeed.

Do we really need to do this? ::

Yes.

How often should we do releases? ::

This depends very much on the nature of your project and the expectations of your community and stake holders. If you're not sure, connect with your mentors and top-level project for guidance.

How much effort should we put into this? ::

The amount of effort varies based on the nature of the team, and expectations of the community and stake holders. Generally, though, a project team shouldn't spend more than a couple of hours working directly on the formal aspects of the release review. If the amount of effort seems too onerous, you may be trying too hard. Connect with your project mentors, top-level project's PMC, or the mailto:{emoEmail}[EMO] for guidance.

Do I need to engage in a release review? ::

If the the project team wants to issue an official major or minor release and has not engaged in a release review (or progress review) within a year of the planned release date, then a release review is required.

What is the difference between a release review and progress review? ::

In practice, there is really no difference. The activities involved are the same and a project may create major and minor releases for an entire year following a successful release or progress review.
+
Progress reviews were added to the {edpLink} primarily to support the {efspUrl}[Eclipse Foundation Specification Process], which requires that specification project teams engage periodic reviews that do not necessarily align with releases.
+
In cases where, for example, a project team has gone an extended period of time without having engaged in a review, the project leadership chain may  compel the project team to engage in a progress review to ensure that the project team is following the processes and is generally engaging in the sorts of activities required for success.

How do I submit the IP Log for review? ::

Click the btn:[Submit] button on the <<ip-iplog-generator,IP Log generator>>. You need to be logged in as project committer to have access to this button.

Can I accept contributions after I submit the IP Log for review? ::

The short answer is _yes_. Please do accept contributions. If you require a new contribution questionnaire (for either a third-party library or code contribution) after submitting the IP Log for review, please ask the mailto:{ipTeamEmail}[IP Team] if they want you to resubmit the IP Log.

How do I obtain PMC approval? ::

Send the the PMC a note via the top-level project's _PMC_ mailing list with a link to the release record. Note that the release record page has a handy link labeled menu:Committer Tools[Send Email the PMC].

I need to do a release now. Can you fast-track the review? ::

While we do try to be as accommodating as possible, the answer is no. We have a well-defined process with predictable dates. Please plan accordingly.

Can a project in the incubation phase do releases? ::

Yes. In fact, we encourage projects to do at least one release while in incubation phase.

What restrictions are placed on version names for incubating projects? ::

Projects in the incubation phase generally use version numbers that are less than 1.0. This is, however, a convention not a rule. If it makes sense for you community and adopters to use higher numbers, then do so. If you're not sure, ask your top-level project PMC for advice.

How do I name/number milestone builds? ::

Milestone builds should contain the name/number of the release suffixed with "Mn" (e.g. the second milestone for EGit 3.2 may have a file named `egit-3.2M2`). Projects in the incubation phase may produce milestone builds for their graduation release, e.g `myProject-1.0M2`.

How can I get help? ::

Contact your mentors (for projects in the incubation phase), top-level project PMC, or the mailto:{emoEmail}[EMO].