Standardize Markdown headings; enforce MD003 with markdownlint

Author: jbampton

.github/linters/.markdown-lint.yml

@@ -18,9 +18,6 @@
 # MD001/heading-increment Heading levels should only increment by one level at a time
 MD001: false
 
-# MD003/heading-style Heading style
-MD003: false
-
 # MD004/ul-style Unordered list style
 MD004: false
 

.pre-commit-config.yaml

@@ -94,3 +94,4 @@ repos:
         args: [--config=.github/linters/.markdown-lint.yml]
         types: [markdown]
         files: \.(md|mdown|markdown)$
+        exclude: ^CHANGES\.md$

CONTRIBUTING.md

@@ -1,40 +1,36 @@
-Contributing to Apache CloudStack (ACS)
-=======================================
+# Contributing to Apache CloudStack (ACS)
+
+## Summary
 
-Summary
--------
 This document covers how to contribute to the ACS project. ACS uses GitHub PRs to manage code contributions.
 These instructions assume you have a GitHub.com account, so if you don't have one you will have to create one. Your proposed code changes will be published to your own fork of the ACS project, and you will submit a Pull Request for your changes to be added.
 
 _Let's get started!!!_
 
-Bug fixes
----------
+## Bug fixes
 
 It's very important that we can easily track bug fix commits, so their hashes should remain the same in all branches.
 Therefore, a pull request (PR) that fixes a bug, should be sent against a release branch.
 This can be either the "current release" or the "previous release", depending on which ones are maintained.
 Since the goal is a stable main, bug fixes should be "merged forward" to the next branch in order: "previous release" -> "current release" -> main (in other words: old to new)
 
-Developing new features
------------------------
+## Developing new features
 
 Development should be done in a feature branch, branched off of main.
 Send a PR(steps below) to get it into main (2x LGTM applies).
 PR will only be merged when main is open, will be held otherwise until main is open again.
 No back porting / cherry-picking features to existing branches!
 
-PendingReleaseNotes file
-------------------------
+## PendingReleaseNotes file
+
 When developing a new feature or making a (major) change to an existing feature you are encouraged to append this to the PendingReleaseNotes file so that the Release Manager can
 use this file as a source of information when compiling the Release Notes for a new release.
 
 When adding information to the PendingReleaseNotes file make sure that you write a good and understandable description of the new feature or change which you have developed.
 
 Updating the PendingReleaseNotes file is preferably a part of the original Pull Request, but that is up to the developers' discretion.
 
-Fork the code
--------------
+## Fork the code
 
 In your browser, navigate to: [https://github.com/apache/cloudstack](https://github.com/apache/cloudstack)
 
@@ -51,8 +47,7 @@ $ git fetch upstream
 $ git rebase upstream/main
 ```
 
-Making changes
---------------
+## Making changes
 
 It is important that you create a new branch to make changes on and that you do not change the `main` branch (other than to rebase in changes from `upstream/main`).  In this example I will assume you will be making your changes to a branch called `feature_x`.  This `feature_x` branch will be created on your local repository and will be pushed to your forked repository on GitHub.  Once this branch is on your fork you will create a Pull Request for the changes to be added to the ACS project.
 
@@ -68,8 +63,7 @@ $ git commit -a -m "descriptive commit message for your changes"
 
 > The `-b` specifies that you want to create a new branch called `feature_x`.  You only specify `-b` the first time you checkout because you are creating a new branch.  Once the `feature_x` branch exists, you can later switch to it with only `git checkout feature_x`.
 
-Rebase `feature_x` to include updates from `upstream/main`
-------------------------------------------------------------
+## Rebase `feature_x` to include updates from `upstream/main`
 
 It is important that you maintain an up-to-date `main` branch in your local repository.  This is done by rebasing in the code changes from `upstream/main` (the official ACS project repository) into your local repository.  You will want to do this before you start working on a feature as well as right before you submit your changes as a pull request.  I recommend you do this process periodically while you work to make sure you are working off the most recent project code.
 
@@ -89,8 +83,7 @@ $ git rebase main
 
 > Now your `feature_x` branch is up-to-date with all the code in `upstream/main`.
 
-Make a GitHub Pull Request to contribute your changes
------------------------------------------------------
+## Make a GitHub Pull Request to contribute your changes
 
 When you are happy with your changes, and you are ready to contribute them, you will create a Pull Request on GitHub to do so.  This is done by pushing your local changes to your forked repository (default remote name is `origin`) and then initiating a pull request on GitHub.
 
@@ -114,8 +107,7 @@ To initiate the pull request, do the following:
 
 If you are requested to make modifications to your proposed changes, make the changes locally on your `feature_x` branch, re-push the `feature_x` branch to your fork.  The existing pull request should automatically pick up the change and update accordingly.
 
-Cleaning up after a successful pull request
--------------------------------------------
+## Cleaning up after a successful pull request
 
 Once the `feature_x` branch has been committed into the `upstream/main` branch, your local `feature_x` branch and the `origin/feature_x` branch are no longer needed.  If you want to make additional changes, restart the process with a new branch.
 
@@ -129,6 +121,6 @@ $ git branch -D feature_x
 $ git push origin :feature_x
 ```
 
-Release Principles
-------------------
+## Release Principles
+
 Detailed information about ACS release principles is available at https://cwiki.apache.org/confluence/display/CLOUDSTACK/Release+principles+for+Apache+CloudStack+4.6+and+up

plugins/storage/volume/storpool/README.md

@@ -341,8 +341,6 @@ corresponding system disk offering.
 
 CloudStack has no way to specify max BW. Do they want to be able to specify max BW only is sufficient.
 
-================================================================================
-
 StorPool provides the ‘storpool_qos’ service ([QoS user guide](https://kb.storpool.com/storpool_misc/qos.html#storpool-qos-user-guide)) that tracks and configures the storage tier for all volumes based on a specifically provided `qc` tag specifying the storage tier for each volume.
 
 To manage the QoS limits with a `qc` tag, you have to add a `qc` tag resource detail to each disk offering to which a tier should be applied, with a key `SP_QOSCLASS` and the value from the configuration file for the `storpool_qos` service:

test/integration/plugins/linstor/README.md

@@ -1,9 +1,9 @@
 # Linstor storage plugin
-==================================
+
 This directory contains the basic VM, Volume life cycle tests for Linstor storage pool (in KVM hypervisor).
 
-# Running tests
-===============
+## Running tests
+
 To run the basic volume tests, first update the below test data of the CloudStack environment
 
 ```

test/integration/plugins/scaleio/README.md

@@ -1,9 +1,9 @@
 # PowerFlex/ScaleIO storage plugin
-==================================
+
 This directory contains the basic VM, Volume life cycle tests for PowerFlex/ScaleIO storage pool (in KVM hypervisor).
 
-# Running tests
-===============
+## Running tests
+
 To run the basic volume tests, first update the below test data of the CloudStack environment
 
 ```

test/systemvm/README.md

@@ -1,14 +1,14 @@
-Requirements
-============
+# Requirements
+
 To run these tests, first get the vagrant setup for the systemvm working,
 see ../../tools/vagrant/systemvm.
 
 Then, install dependencies
 
     pip install nose paramiko python-vagrant envassert cuisine fabric
 
-Running tests
-=============
+## Running tests
+
 Then run the tests using your favorite python unittest runner
 
     nosetests-2.7
@@ -22,8 +22,8 @@ not recommended.
 
 You can also run these tests out of the box with PyDev or PyCharm or whatever.
 
-Adding tests
-============
+## Adding tests
+
 Simply create new test_xxx.py files with test cases that extend from
 SystemVMTestCase.
 
@@ -55,8 +55,8 @@ class HelloSystemVMTestCase(SystemVMTestCase):
         assert something_to_do('foo')
 ```
 
-Edit, test, edit, test
-======================
+## Edit, test, edit, test
+
 The SystemVM Vagrantfile sets up rsync from systemvm/patches. These rsyncs run
 once, when you type 'vagrant up'. To do these rsyncs every time you change a
 patch file, run 'vagrant rsync-auto'. With that, your development process can

tools/appliance/README.md

@@ -1,3 +1,4 @@
+<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
@@ -14,8 +15,7 @@ software distributed under the License is distributed on an
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-
-===========================================================
+-->
 
 # Introduction
 

tools/devcloud-kvm/README.md

@@ -1,3 +1,4 @@
+<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
@@ -14,8 +15,7 @@ software distributed under the License is distributed on an
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-
-===========================================================
+-->
 
 This directory hosts configs for setting up the devcloud-kvm
 environment.

tools/marvin/marvin/misc/build/CI.md

@@ -17,8 +17,7 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-about
-=====
+# about
 
 This document talks about the *evolving* continuous test infrastructure used to setup, deploy, configure and test Apache CloudStack. Information here is useful for anyone involved in build, test, continuous integration even operators of CloudStack.
 
@@ -96,22 +95,19 @@ b. multiple cluster
 c. inter-zone tests
 d. multi-pod tests
 
-marvin integration
-==================
+## marvin integration
 
 once cloudstack has been installed and the hypervisors prepared we are ready to use marvin to stitch together zones, pods, clusters and compute and storage to put together a 'cloud'.  once configured - we perform a cursory health check to see if we have all systemVMs running in all zones and that built-in templates are downloaded in all zones. Subsequently, we are able to launch tests on this environment
 
 Only the latest tests from git are run on the setup. This allows us to test in a pseudo-continuous fashion with a nightly build deployed on the environment. Each test run takes a few hours to finish.
 
-control via github
-==================
+## control via github
 
 there are two GitHub repositories controlling the test infrastructure.
 a. The puppet recipes at gh:acs-infra-test
 b. The gh:cloud-autodeploy repo that has the scripts to orchestrate the overall workflow
 
-workflow
-========
+## workflow
 
 When jenkins triggers the job following sequence of actions occur on the test infrastructure
 
@@ -149,11 +145,10 @@ The $distro argument chooses the hostOS of the mgmt server - this can be ubuntu
 
 12. Tests are run using the nose test runner with the marvin plugin and reports are recorded by jenkins.
 
-limitations
-===========
+## limitations
+
+## enhancements
 
-enhancements
-============
 - packaging tests
 - puppetize the cobbler appliance
 - dogfooding
@@ -164,14 +159,12 @@ enhancements
 - external devices (LB, VPX, FW)
 - mcollective?
 
-future
-======
+## future
+
 - not everyone deploys cloudstack the same
 - multiple hv environments with multiple hv configurations
 - multiple storage configurations
 
-troubleshooting
-===============
+## troubleshooting
 
-acknowledgements
-================
+## acknowledgements