Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 3 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# OpenSSL Technical Policies

This repository contains the technical policies and procedures established by
the [OTC] in accordance with the [project bylaws] and the requirements specified
by the [OMC].

the OpenSSL Foundation and the OpenSSL Corporation in accordance with the
[project bylaws].

## The Policies

Expand All @@ -25,9 +24,7 @@ each in a separate file. The format of those records is described in the
[voting-procedure] policy.


[OMC]: https://github.com/openssl/general-policies/blob/master/policies/glossary.md#otc
[OTC]: https://github.com/openssl/general-policies/blob/master/policies/glossary.md#omc
[project bylaws]: https://www.openssl.org/policies/omc-bylaws.html
[project bylaws]: https://openssl-library.org/about/bylaws/
[policy-change-process]: ./policies/policy-change-process.md
[voting-procedure]: ./policies/voting-procedure.md
[policies]: ./policies
Expand Down
23 changes: 13 additions & 10 deletions policies/branch-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ The openssl repository contains the following maintained branches:
happens there.
- According to [stable release update policy] only bug fixes and
documentation changes are allowed.
- By exception given by OMC also other types of pull requests can be merged.
- By exception given by the OpenSSL Foundation or the OpenSSL Corporation
also other types of pull requests can be merged.
- Bug fix and documentation pull requests must be always merged to the
latest branch where the bug or documentation deficiency is present including
the future major and minor branches.
Expand All @@ -30,8 +31,9 @@ The openssl repository contains the following maintained branches:
## A future major branch

- The development of a future major release happens there. Implicitly it
means that any API/ABI breaking changes are allowed but OMC can (and
usually will) limit the extent of the breakage allowed.
means that any API/ABI breaking changes are allowed but the OpenSSL
Foundation or the OpenSSL Corporation can (and usually will) limit the
extent of the breakage allowed.
- Major features are allowed. Examples of a major feature: A completely
new implementation of a protocol. New API for pluggable crypto modules.
- Major refactoring is allowed. Examples of major refactoring: Splitting
Expand All @@ -40,17 +42,17 @@ The openssl repository contains the following maintained branches:
is a major release and there are no changes accepted for a future major
release yet.
- All changes specifically targetting this branch instead of the default
development branch must be approved by OTC by consensus during
a meeting or a formal vote.
development branch must be approved by the OpenSSL Foundation or
OpenSSL Corporation.

## A future minor branch

- The development of the minor release that is supposed to be released
after the release currently being developed at the default development branch
happens there.
- No API/ABI breaking changes are allowed.
- No major features are allowed unless explicitly acked by OMC as targeted for
the minor release.
- No major features are allowed unless explicitly acked by the OpenSSL
Foundation or the OpenSSL Corporation as targeted for the minor release.
- No major refactoring is allowed.
- Any changes (features, bug-fixes, documentation, ...) done on the future
minor branch must be ported or directly cherry-picked to the future major
Expand All @@ -61,8 +63,8 @@ The openssl repository contains the following maintained branches:
be a major release or there are no changes accepted for a future minor
release yet.
- All changes specifically targetting this branch instead of the default
development branch must be approved by OTC by consensus during
a meeting or a formal vote.
development branch must be approved by the OpenSSL Foundation or the
OpenSSL Corporation.

## Branch and tag naming

Expand Down Expand Up @@ -92,6 +94,7 @@ of OpenSSL-1.1.1 are named `OpenSSL_1_1_1<fix-letter(s)>`.
## Branch creation

The exact times when the future major and minor branches are created are
undefined by the policy as that is an OMC responsibility to decide.
undefined by the policy as that is responsibility of the OpenSSL Foundation
or the OpenSSL Corporation to decide.

[stable release update policy]: /policies/technical/stable-release-updates/
109 changes: 4 additions & 105 deletions policies/design-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,6 @@ It is an explicit objective of this policy to support and encourage this
agile-style process, as opposed to a waterfall-style process in which designs
must be approved and finalised prior to implementation.

This policy adopts a graded system of review in which the degree of formal
approval by the OTC which a design must undergo is proportionate to the scope
and risks of the design. For example, a design which involves new or evolved
public APIs may require a greater amount of scrutiny, whereas a purely internal
design may require that the OTC simply be notified of the design document and
invited to comment, with implicit approval in the absence of objections.

## Requirement for Design Documents

A design document is required for any proposed enhancement which adds
Expand All @@ -46,7 +39,7 @@ one. For example, if an enhancement adds a new internal module with clearly
delineated boundaries with a documented internal API which can be consumed by
other code internal to OpenSSL, a design document is desirable. This example is
not exhaustive. The proposer may use their discretion in determining whether a
design document is desirable, but any OTC member may require that a design
design document is desirable, but any Committer may request that a design
document be produced.

## Contents of Design Documents
Expand All @@ -60,8 +53,7 @@ In general, where produced, a design document should include discussion of:
- anything which is expressly not a requirement;

- the origins or underlying motivations of those requirements (or
non-requirements) in turn (for example, do the requirements originate from the
OMC or are they themselves a product of other technical requirements?);
non-requirements) in turn;

- significant assumptions or limitations of scope being made as part of the
design (which might cause a design to become suboptimal or inapplicable if
Expand Down Expand Up @@ -115,83 +107,8 @@ sections will be relevant to all design documents, and design document authors
can and should deviate from this structure where this leads to a more
comprehensible or useful document.

## Levels of Scrutiny

There are three levels of scrutiny which can be applied to a design, listed
below in ascending order of severity:

- Notify
- Present
- Approve

These levels work as follows:

- At the **Notify** level, the OTC is notified of a new design
when it is available for review, via an email to the openssl-project mailing list.
OTC members and committers and the public can review and comment on the design.
A minimum waiting time of one week after the notification is made applies to
ensure OTC members have the opportunity to review the design.

The notification does not need to be made by the author of the design
document.

- At the **Present** level, the OTC is notified of a new design
in the same way that it is at the Notify level. The same minimum waiting time
applies. The design is also introduced and explained in a presentation given
to the OTC in a meeting of the OTC. The OTC has opportunities to ask
questions and raise concerns at this meeting. This presentation may be given
by the author of the design but need not be.

- At the **Approve** level, the OTC must explicitly approve the design
by making a decision as the OTC. The OTC should be notified of a
new design in the same way they are notified at the Notify level.
A presentation to the OTC may be made but is not required.

When a design is produced, it should be submitted to the OpenSSL repository as a
PR. It should be determined which level of scrutiny is appropriate according to
this policy and this should be noted in the PR. Any applicable actions (such as
notifying the OTC via the openssl-project list) should be carried out once the
design is ready for review.

Any OTC member may object to the processing of a design at a given level of
scrutiny and require that a higher level be used.

A proposer may choose to use a higher level of scrutiny than is required.

## Selecting a Level

To determine the level of scrutiny which must be applied to a design by default,
follow the following process:

- Any design which proposes to create significant new public APIs, or
non-trivially evolve or modify existing public APIs, must use at least the
Present level of scrutiny.

- Any other design may use the Notify level of scrutiny.

## Checklists

### Checklist for the Notify Level

- Design document published as a PR on GitHub
- OTC notified and invited to comment or object via an email to
openssl-project list
- At least one week has passed from OTC notification

### Checklist for the Present Level

- Design document published as a PR on GitHub
- OTC notified and invited to comment or object via an email to
openssl-project list
- Presentation given to a quorate OTC meeting by the design's proposer, and
OTC has had opportunity to ask questions and discuss the proposal
- At least one week has passed from OTC notification

### Checklist for the Approve Level

- Design document published as a PR on GitHub
- OTC makes a decision approving the design. The decision is made according to
standard OTC policies.
When a design is produced, it should be submitted to the OpenSSL repository as
a PR.

## Implementation

Expand All @@ -201,27 +118,9 @@ facilitates an agile process and helps to improve the design document, as
implementation will often lead to an improved understanding of the problem
domain, leading in turn to an improved design document.

A design document PR, or a PR implementing said design, should not be merged
until the relevant requirements for the level of scrutiny used have been
satisfied. It is permissible for a design document and an implementation to be
part of the same PR.

## Revisions to Pending Designs

Where changes to a design document need to be made (for example, due to an
evolved understanding of the problem domain arising from an implementation in
progress), if the design document has already been merged, a new PR should be
raised and this will go through the normal process described above.

If the design document has not yet merged:

- if the Notify or Present level of scrutiny is being used, it may be changed
by the proposer freely. Another notification to the openssl-project list may
be made if the changes are deemed very major but is not required.

- if the Approve level of scrutiny is being used, and the approval has already
been finalised or a vote is ongoing, the design should not be changed and a
new PR should be raised. The document may be changed freely if it has been
decided that the Approve level of scrutiny is to be used but a vote has not
yet opened.

79 changes: 0 additions & 79 deletions policies/policy-change-process.md

This file was deleted.

29 changes: 13 additions & 16 deletions policies/release-requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ by the first beta pre-release. The following release requirements apply to beta
pre-releases.

- [ ] The code is functionally complete in regards to the particular release
objectives as set by OMC and OTC.
- [ ] There is no remaining refactoring required by OMC or OTC for the release.
objectives as set by the OpenSSL Foundation and the OpenSSL Corporation.
- [ ] There is no remaining refactoring required for the release.
- [ ] There are no remaining API changes required for the release.
_This applies only to beta releases of a major release as API changes
are not allowed on minor releases._
Expand All @@ -47,8 +47,9 @@ pre-releases.
regression or security fixes should be merged during the freeze.
- [ ] For 2 days before the release there should be no changes to ensure the daily
CI builds run on the development tree tip.
- [ ] In case of the first beta release the OTC should explicitly approve
that the source is ready for a release with a vote.
- [ ] In case of the first beta release the OpenSSL Foundation and the OpenSSL
Corporation engineering managers should explicitly approve that the source is
ready for a release.

## Major and Minor Releases

Expand All @@ -68,8 +69,8 @@ stability requirements as those should be held already by the beta releases.
or security fixes should be merged during the freeze.
- [ ] For 2 days before the release there should be no changes to ensure the daily
CI builds run on the development tree tip.
- [ ] The OTC should explicitly approve that the source is ready for a release with
a vote.
- [ ] The OpenSSL Foundation and the OpenSSL Corporation engineering managers
should explicitly approve that the source is ready for a release.

## Patch Releases

Expand All @@ -95,7 +96,7 @@ a minimum amount of regressions in between the patch releases.
## Triage Process

The issues and pull requests in GitHub must be assigned a `triaged: *` label by
an OTC member according to what is the type (feature, bug, documentation,
a Committer according to what is the type (feature, bug, documentation,
refactoring, ...) of the issue or pull request. When the triage happens for an
issue or pull request that is a bug/bug fix, it must be assessed whether the
bug is a regression or not.
Expand All @@ -105,23 +106,19 @@ the next release from the development tree is done. However sometimes that
might not be reasonably possible due to time, resource, or fix complexity
constraints.

In that case OTC should explicitly acknowledge that the regression is not to be
fixed before the release is done. That is done by assigning a milestone by
which the regression must be fixed and the `triaged: OTC evaluated` label.

The triage ideally happens as soon as possible, however the triage process can
sometimes be costly, so we aim to have issues triaged no later than 4 days
after they are reported.

## Responsibilities

The OTC is responsible to ensure the releases conform to these requirements.
How exactly the OTC handles this responsibility is undefined here on purpose
except for the explicit votes required for the first beta release and the
major or minor releases.
The OpenSSL Foundation and the OpenSSL Corporation engineering managers are
jointly responsible to ensure the releases conform to these requirements.
How exactly the they handle this responsibility is undefined here on purpose.

For example the responsibility to follow the release requirements can be
delegated by the OTC to the person (or the team) preparing the release.
delegated by the engineering managers to the person (or the team) preparing
the release.

[alpha]: /policies/general/glossary/#alpha-release
[beta]: /policies/general/glossary/#beta-release
Expand Down
3 changes: 2 additions & 1 deletion policies/stable-release-updates.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ New tests and test cases are allowed only as part of a bug fix.
Patch release commits are obviously allowed (updates to CHANGES.md, NEWS.md,
version, and copyright updates).

**Exceptions to this policy require OTC approval.**
**Exceptions to this policy require explicit approval of the OpenSSL
Foundation or the OpenSSL Corporation directors.**

*The policy for changes allowed in stable releases applies also to
pre-release branches after the first beta release.*
Loading