make markdown markup consistent

Reviewed-by: Richard Levitte <[email protected]>
Reviewed-by: Anton Arapov <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
Reviewed-by: Tomas Mraz <[email protected]>

Author: quarckster

README.md

@@ -1,13 +1,11 @@
-OpenSSL Technical Policies
-==========================
+# 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 Policies
-------------
+## The Policies
 
 The policies are stored in the [policies] subdirectory, each in
 a separate markdown file called `policy-name.md` where `policy-name` is a short
@@ -20,8 +18,7 @@ an OTC vote. The details are regulated by the [policy-change-process] and the
 [voting-procedure] policy.
 
 
-The Vote Records
-------------------
+## The Vote Records
 
 The records of the policy votes are stored in the [votes] subdirectory,
 each in a separate file. The format of those records is described in the

policies/api-compat.md

@@ -1,5 +1,4 @@
-Policy on API compatibility in minor releases
-=============================================
+# Policy on API compatibility in minor releases
 
 The public [API] of the OpenSSL libraries is defined as functions, macros, data
 structure declarations, typedefs, and data variables in header files in the

policies/assembler.md

@@ -1,5 +1,4 @@
-Policy for Accepting Assembler Optimisations
-============================================
+# Policy for Accepting Assembler Optimisations
 
 New assembler optimisations for any algorithm having a C based implementation in
 any provider are always acceptable (subject to standard review procedures) for

policies/branch-policy.md

@@ -1,9 +1,8 @@
-Branch Policy
-=============
+# Branch Policy
 
 The openssl repository contains the following maintained branches:
 
-### The default development branch
+## The default development branch
 
 - Any type (bug fix, feature, refactoring, ...) of pull requests is allowed.
 - The development of the next minor or major release happens there.
@@ -15,7 +14,7 @@ The openssl repository contains the following maintained branches:
   By this we must ensure that no features or bug fixes are unintentionally
   lost in future major or minor releases.
 
-### The supported release branches
+## The supported release branches
 
 - The development of the next patch releases of supported stable releases
   happens there.
@@ -28,7 +27,7 @@ The openssl repository contains the following maintained branches:
   It can be then merged (backported or directly cherry-picked) to all
   older branches where the deficiency is present.
 
-### A future major branch
+## 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
@@ -44,7 +43,7 @@ The openssl repository contains the following maintained branches:
   development branch must be approved by OTC by consensus during
   a meeting or a formal vote.
 
-### A future minor branch
+## 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
@@ -65,8 +64,7 @@ The openssl repository contains the following maintained branches:
   development branch must be approved by OTC by consensus during
   a meeting or a formal vote.
 
-Branch and tag naming
----------------------
+## Branch and tag naming
 
 The branch where the development of the next release is happening is called
 `openssl-x.y` where `x` is the current major version number and `y` is the
@@ -91,8 +89,7 @@ patch releases, `openssl-x.y.0-alphaN` for alpha releases, and
 `openssl-x.y.0-betaN` for beta releases. As a legacy exception the fix releases
 of OpenSSL-1.1.1 are named `OpenSSL_1_1_1<fix-letter(s)>`.
 
-Branch creation
----------------
+## 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.

policies/design-process.md

@@ -1,8 +1,6 @@
-Design Process Policy
-=====================
+# Design Process Policy
 
-Objectives
-----------
+## Objectives
 
 The objective of the design process is to increase the quality of the software
 engineering process. The production of design documents confers the following
@@ -36,8 +34,7 @@ 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
---------------------------------
+## Requirement for Design Documents
 
 A design document is required for any proposed enhancement which adds
 significant new APIs or non-trivially evolves or modifies existing APIs.
@@ -52,8 +49,7 @@ 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
 document be produced.
 
-Contents of Design Documents
-----------------------------
+## Contents of Design Documents
 
 In general, where produced, a design document should include discussion of:
 
@@ -119,8 +115,7 @@ 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
-------------------
+## Levels of Scrutiny
 
 There are three levels of scrutiny which can be applied to a design, listed
 below in ascending order of severity:
@@ -163,8 +158,7 @@ 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
------------------
+## Selecting a Level
 
 To determine the level of scrutiny which must be applied to a design by default,
 follow the following process:
@@ -175,8 +169,7 @@ follow the following process:
 
   - Any other design may use the Notify level of scrutiny.
 
-Checklists
-----------
+## Checklists
 
 ### Checklist for the Notify Level
 
@@ -200,8 +193,7 @@ Checklists
   - OTC makes a decision approving the design. The decision is made according to
     standard OTC policies.
 
-Implementation
---------------
+## Implementation
 
 It is not required to wait for a design document to be approved and merged
 before beginning implementation. Implementation can begin immediately. This
@@ -214,8 +206,7 @@ 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
-----------------------------
+## 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

policies/policy-change-process.md

@@ -1,14 +1,12 @@
-Policy on Proposing Technical Policy Changes
-============================================
+# Policy on Proposing Technical Policy Changes
 
 This policy represents the way that any additions or changes to the
 existing policies are proposed, edited, finalized, and approved.
 
 The process for minor changes is described in the
 [Minor Edits](#minor-edits) section.
 
-Policy Change Proposal
-----------------------
+## Policy Change Proposal
 
 The policy changes or additions are submitted as pull requests in the
 technical-policies repository on GitHub OpenSSL project. Anyone with
@@ -27,8 +25,7 @@ and the reasons why the change is proposed.
 After the pull request has been created the author MUST announce the policy
 change proposal on the openssl-project mailing list.
 
-The Review Process
----------------------
+## The Review Process
 
 If the submitter is not a member of OTC, an OTC member is selected to watch
 over the review process and propose the final approval vote.
@@ -45,14 +42,12 @@ it is not an absolute requirement.
 The review process is fully public in the sense that anyone can add
 comments to the pull request and see comments made by others.
 
-Withdrawal
-----------
+## Withdrawal
 
 To withdraw the change the submitter of the pull request just closes the
 pull request.
 
-The Approval Process
---------------------
+## The Approval Process
 
 When there are no further changes proposed on the pull request and the
 minimum time for which it must be open passes the pull request is marked
@@ -70,8 +65,7 @@ and closing the pull request without merging.
 If the policy change is approved, the pull request is merged to the
 master branch of the technical-policies repository.
 
-Minor Edits
------------
+## Minor Edits
 
 Minor policy edits that do not change the meaning of the edited
 policies do not require this voting process. Typical examples of such edits

policies/release-requirements.md

@@ -1,5 +1,4 @@
-Release Requirements Policy
-===========================
+# Release Requirements Policy
 
 The OpenSSL project team creates the following 5 types of OpenSSL software
 releases:
@@ -13,17 +12,15 @@ releases:
 This policy defines the requirements on the state of a branch in the source
 tree that must be met before a release from that branch can be done.
 
-Alpha Pre-releases
-------------------
+## Alpha Pre-releases
 
 As this is just a preview release for testing things that have been worked
 on in the development branch, the requirements are minimal.
 
 - The CI must pass on the tip of the development branch before the release
   commits were added to the tree.
 
-Beta Pre-releases
------------------
+## Beta Pre-releases
 
 The API and ABI should be stable and the source code should be feature complete
 by the first beta pre-release. The following release requirements apply to beta
@@ -53,8 +50,7 @@ pre-releases.
 - [ ] In case of the first beta release the OTC should explicitly approve
   that the source is ready for a release with a vote.
 
-Major and Minor Releases
-------------------------
+## Major and Minor Releases
 
 As the release comes after the beta releases there is no need to repeat the
 stability requirements as those should be held already by the beta releases.
@@ -75,8 +71,7 @@ stability requirements as those should be held already by the beta releases.
 - [ ] The OTC should explicitly approve that the source is ready for a release with
   a vote.
 
-Patch Releases
---------------
+## Patch Releases
 
 The patch releases follow a similar process to major and minor releases with
 some simplifications as they are much more frequent and the tree stability
@@ -97,8 +92,7 @@ a minimum amount of regressions in between the patch releases.
 - [ ] Embargoed security fixes are excepted from the rule above as they cannot
   be merged to the public tree before the release is being prepared.
 
-Triage Process
---------------
+## 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,
@@ -119,8 +113,7 @@ 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
-----------------
+## 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

policies/stable-release-updates.md

@@ -1,10 +1,8 @@
-Stable Release Updates Policy
-=============================
+# Stable Release Updates Policy
 
 This policy covers allowed changes on release branches.
 
-Definitions
------------
+## Definitions
 
 A **stable release** is a series beginning with a major or minor release that
 is not a pre-release, and all its updates.
@@ -68,8 +66,7 @@ An **end-user documentation** is **not**:
 - comments in the code (including public header files)
 - internal documentation (doc/internal)
 
-Changes allowed in stable releases and pre-releases after the first beta
-------------------------------------------------------------------------
+## Changes allowed in stable releases and pre-releases after the first beta
 
 No API or ABI breaking changes are allowed in a minor or patch release.
 

policies/testing.md

@@ -1,5 +1,4 @@
-Testing Policy
-==============
+# Testing Policy
 
 This applies to all [stable] and development branches of the main code repository.
 
@@ -42,8 +41,7 @@ A test may be omitted where writing the test would result in disproportionately
 more effort than writing the code being tested. For example, difficult to
 reproduce error conditions.
 
-Triage Labels
--------------
+## Triage Labels
 
 Before approving a PR, the applicability of the testing policy to the PR must
 be assessed and an appropriate label applied to the PR. One of the following
@@ -82,8 +80,7 @@ are being made prior to making any more specific prescriptions. For example,
 this labelling allows obtaining a list of merged PRs for which a decision was
 made to defer adding tests, but for which tests have not yet been added.
 
-Performance Testing
--------------------
+## Performance Testing
 
 Performance testing should be performed automatically via [CI] on a regular basis
 for certain components as defined by the [OTC].
@@ -96,8 +93,7 @@ Examples of performance testing that should be considered include:
 
 Performance figures should be collected and tracked over time.
 
-Recommendations
----------------
+## Recommendations
 
 This section makes recommendations that are not mandatory but should be
 considered.