Resolve markdown linter warnings

Signed-off-by: Marco Franssen <[email protected]>
notaryproject · Oct 19, 2021 · 4142467 · 4142467
1 parent 1ce7178
commit 4142467
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -15,19 +15,22 @@ Notation is a project to add signatures as standard items in the registry ecosys
 
 ## Notation Quick Start
 
-- Install the Notation CLI from [Notation Releases][notation-releases]  
+- Install the Notation CLI from [Notation Releases][notation-releases]
+
   ```bash
   curl -Lo notation.tar.gz https://github.com/shizhMSFT/notation/releases/download/v0.5.2/notation_0.5.2_linux_amd64.tar.gz
   tar xvzf notation.tar.gz -C ~/bin notation
   ```
+
 - Build, Push, Sign, Verify the `net-monitor` software
+
   ```bash
   export IMAGE=localhost:5000/net-monitor:v1
   docker build -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main
   docker push $IMAGE
   notation cert generate-test --default --trust "wabbit-networks-dev"
   notation sign $IMAGE
-  notation list $IMAGE 
+  notation list $IMAGE
   notation verify $IMAGE
   ```
 
@@ -40,16 +43,14 @@ Notation is a project to add signatures as standard items in the registry ecosys
 
 ## Core Documents
 
-* [Governance for Notation](https://github.com/notaryproject/notary/blob/master/GOVERNANCE.md)
-* [Maintainers and reviewers list](https://github.com/notaryproject/notary/blob/master/MAINTAINERS)
+- [Governance for Notation](https://github.com/notaryproject/notary/blob/master/GOVERNANCE.md)
+- [Maintainers and reviewers list](https://github.com/notaryproject/notary/blob/master/MAINTAINERS)
 
 ## Community
 
-* Regular conversations for Notation occur on the [Cloud Native Computing Slack](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287?) channel.
-
-* Please see the [CNCF Calendar](https://www.cncf.io/calendar/) for community meeting details.
-
-* Meeting notes are captured on [hackmd.io](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw).
+- Regular conversations for Notation occur on the [Cloud Native Computing Slack](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287?) channel.
+- Please see the [CNCF Calendar](https://www.cncf.io/calendar/) for community meeting details.
+- Meeting notes are captured on [hackmd.io](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw).
 
 ## Release Management
 
@@ -59,7 +60,6 @@ The Notation release process is defined in [RELEASE_MANAGEMENT.md](RELEASE_MANAG
 
 Support for the Notation project is defined in [supported releases](RELEASE_MANAGEMENT.md#supported-releases).
 
-
 ## Code of Conduct
 
 This project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for further details.
@@ -68,9 +68,6 @@ This project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foun
 
 This project is covered under the Apache 2.0 license. You can read the license [here](LICENSE).
 
-=======
-
 [notation-releases]:      https://github.com/shizhMSFT/notation/releases/tag/v0.5.0
 [artifact-manifest]:      https://github.com/oras-project/artifacts-spec/blob/main/artifact-manifest.md
 [cncf-distribution]:      https://github.com/oras-project/distribution
-
diff --git a/RELEASE_MANAGEMENT.md b/RELEASE_MANAGEMENT.md
@@ -2,12 +2,12 @@
 
 ## Overview
 
-This document describes Notation project release management, which includes release versioning, supported releases, and supported upgrades. 
+This document describes Notation project release management, which includes release versioning, supported releases, and supported upgrades.
 
 ## Glossary of Terms
 
 - **X.Y.Z** refers to the version (based on git tag) of Notation that is released. This is the version of the Notation binary.
-- **Breaking changes** refer to schema changes, flag changes, and behavior changes of Notation that may require existing content to be upgraded and may also introduce changes that could break backward compatibility. 
+- **Breaking changes** refer to schema changes, flag changes, and behavior changes of Notation that may require existing content to be upgraded and may also introduce changes that could break backward compatibility.
 - **Milestone** GitHub milestones are used by maintainers to manage each release. PRs and Issues for each release should be created as part of a corresponding milestone.
 - **Patch releases** refer to applicable fixes, including security fixes, may be backported to support releases, depending on severity and feasibility.
 
@@ -17,47 +17,47 @@ All releases will be of the form _vX.Y.Z_ where X is the major version, Y is the
 
 The rest of the doc will cover the release process for the following kinds of releases:
 
-**Major Releases**
+### Major Releases
 
 The Notation project is under active development to reach a stable target version of 1.0.0
 
-**Minor Releases**
+### Minor Releases
 
 - **ALPHA:** X.Y.0-alpha.W, W >= 0 (Branch : main)
-    - Alpha release, cut from main branch
-    - Unstable release which should only be used for early development purposes
-    - Released as needed before we cut a beta X.Y release
-    - Not supported
+  - Alpha release, cut from main branch
+  - Unstable release which should only be used for early development purposes
+  - Released as needed before we cut a beta X.Y release
+  - Not supported
 - **BETA:** X.Y.0-beta.W, W >= 0 (Branch : main)
-    - More stable than the alpha release to be used for testing purposes only
-    - Beta release, cut from main branch
-    - Released as needed before we cut a stable X.Y release
-    - Not supported
+  - More stable than the alpha release to be used for testing purposes only
+  - Beta release, cut from main branch
+  - Released as needed before we cut a stable X.Y release
+  - Not supported
 - **RC:** X.Y.0-rc.W, W >= 0 (Branch : main)
-    - Released as needed before we cut a stable X.Y release
-    - soak for ~ 2 weeks before cutting a stable release
-    - Bugfixes on new features only as reported through usage
-    - Release candidate release, cut from main branch
-    - Not supported
+  - Released as needed before we cut a stable X.Y release
+  - soak for ~ 2 weeks before cutting a stable release
+  - Bugfixes on new features only as reported through usage
+  - Release candidate release, cut from main branch
+  - Not supported
 - **STABLE:** X.Y.0 (Branch: main)
-    - Stable release, cut from master when X.Y milestone is complete
-    - X.Y release branch cut for subsequent patch releases
-    - Supported as per the supported releases process defined below 
+  - Stable release, cut from master when X.Y milestone is complete
+  - X.Y release branch cut for subsequent patch releases
+  - Supported as per the supported releases process defined below
 
-**Patch Releases**
+### Patch Releases
 
 - Patch Releases X.Y.Z, Z > 0 (Branch: release-X.Y, only cut when a patch is needed)
-    - No breaking changes
-    - Applicable fixes, including security fixes, may be cherry-picked from master into the latest supported minor release-X.Y branches. 
-    - Patch release, cut from a release-X.Y branch
+  - No breaking changes
+  - Applicable fixes, including security fixes, may be cherry-picked from master into the latest supported minor release-X.Y branches.
+  - Patch release, cut from a release-X.Y branch
 
 ## Supported Releases
 
 There aren't any stable releases of the Notation project currently. Once a stable version of Notation is released, that version will be supported as follow.
 
 We expect to "support" n (current) and n-1 major.minor releases. "Support" means we expect users to be running that version in production. For example, when v1.3.0 comes out, v1.1.x will no longer be supported for patches and we encourage users to upgrade to a supported version as soon as possible. Support will be provided best effort by the maintainers via GitHub issues and pull requests.
 
-We expect users to stay up-to-date with the versions of Notation they use in production, but understand that it may take time to upgrade. We expect users to be running approximately the latest patch release of a given minor release and encourage users to upgrade as soon as possible. 
+We expect users to stay up-to-date with the versions of Notation they use in production, but understand that it may take time to upgrade. We expect users to be running approximately the latest patch release of a given minor release and encourage users to upgrade as soon as possible.
 
 Applicable fixes, including security fixes, may be cherry-picked into the release branch, depending on severity and feasibility. Patch releases are cut from that branch as needed.
 

diff --git a/hello-signing.md b/hello-signing.md
@@ -12,12 +12,13 @@ This document outlines a range of scenarios progressing from the first use of No
 ## Scenarios
 
 To demonstrate how to store and sign a set of supply chain artifacts, we will walk through a set of scenarios:
+
 - Sign a single container image
-- Publish the container image across public registries, 
+- Publish the container image across public registries,
 - Import public content to a private registry
 - Promote from dev through production
 
-![](./media/notary-e2e-scenarios.svg)
+![Notary end-to-end scenarios](./media/notary-e2e-scenarios.svg)
 
 To illustrate these scenarios we will introduce two example companies:
 
@@ -33,21 +34,26 @@ Wabbit Networks works with Docker Hub to get certified, to help with their custo
 ACME Rockets will only deploy software that's been scanned and approved by the ACME Rockets security team. They know it's been approved because all approved software has been signed by the ACME Rockets security team.
 
 ## Getting Started
-- Setup a few environment variables.  
+
+- Setup a few environment variables.
   >Note see [Simulating a Registry DNS Name](#simulating-a-registry-dns-name) to use `registry.wabbit-networks.io`
+
   ```bash
   export PORT=5000
   export REGISTRY=localhost:${PORT}
   export REPO=${REGISTRY}/net-monitor
   export IMAGE=${REPO}:v1
   ```
+
 - Install [Docker Desktop](https://www.docker.com/products/docker-desktop) for local docker operations
 - Run a local instance of the [CNCF Distribution Registry][cncf-distribution]
+
   ```bash
   docker run -d -p ${PORT}:5000 ghcr.io/oras-project/registry:latest
   ```
-- Acquire the Notation CLI  
-Notation releases can be found at: [Notation Releases][notation-releases]  
+
+- Acquire the Notation CLI (Notation releases can be found at: [Notation Releases][notation-releases])
+
   ```bash
   #LINUX, including WSL
   curl -Lo notation.tar.gz https://github.com/shizhMSFT/notation/releases/download/v0.5.2/notation_0.5.2_linux_amd64.tar.gz
@@ -56,15 +62,19 @@ Notation releases can be found at: [Notation Releases][notation-releases]
 
 ## Building and Pushing
 - Build and Push the `net-monitor` software
+
   ```bash
   docker build -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main
 
   docker push $IMAGE
   ```
+
 - List the image, and any associated signatures
+
   ```bash
   notation list $IMAGE
   ```
+
   At this point, the results are empty, as there are no existing signatures
 
 ## Signing a Container Image
@@ -73,73 +83,93 @@ To get things started quickly, the Notation cli supports generating self signed
 
 - Generate a self-signed test certificate for signing artifacts
   The following will generate a self-signed X.509 certificate under the `~/config/notation/` directory
+
   ```bash
   notation cert generate-test --default "wabbit-networks.io"
   ```
+
 - Sign the container image
+
   ```bash
   notation sign $IMAGE
   ```
+
 - List the image, and any associated signatures
+
   ```bash
-  notation list $IMAGE 
+  notation list $IMAGE
   ```
 
 ## Verify a Container Image Using Notation Signatures
 
 To avoid a Trojan Horse attack, and before pulling an artifact into an environment, it is important to verify that the artifact was unmodified after it was created (integrity), and from an trusted entity (authenticity). Notation uses a set of configured public keys that represent trusted entities, to verify the content. The `notation cert generate-test` command created the public key, however it must be implicitly added for verification to succeed.
 - Attempt to verify the $IMAGE notation signature
+
   ```bash
   notation verify $IMAGE
   ```
+
   *The above verification should fail, as you haven't yet configured the keys to trust.*
+
   ```bash
   2021/09/07 11:40:51 trust certificate not specified
   ```
+
 - To assure users opt-into the public keys they trust, add the key to the trusted store
+
   ```bash
   notation cert add --name "wabbit-networks.io" ~/.config/notation/certificate/wabbit-networks.io.crt
   ```
+
 - Verify the `net-monitor:v1` notation signature
+
   ```bash
   notation verify $IMAGE
   ```
+
   This should now succeed because the image is signed with a trusted public key
 
 ## Reset
+
 To resetting the environment
 
-- Remove keys, certificates and notation `config.json`  
+- Remove keys, certificates and notation `config.json`
   `rm -r ~/.config/notation/`
-- Restart the local registry  
+- Restart the local registry
   `docker rm -f $(docker ps -q)`
 
 ## Simulating a Registry DNS Name
 
 Here are the additional steps to simulate a fully qualified DNS name for wabbit-networks.
 
 - Setup names and variables for `registry.wabbit-networks.io`
+
   ```bash
   export PORT=80
   export REGISTRY=registry.wabbit-networks.io
   export REPO=${REGISTRY}/net-monitor
   export IMAGE=${REPO}:v1
   ```
+
 - Edit `~/.config/notation/config.json` to support local, insecure registries
+
     ```json
     {
       "insecureRegistries": [
         "registry.wabbit-networks.io"
       ]
     }
     ```
+
 - Add a `etc/hosts` entry to simulate pushing to registry.wabbit-networks.io
-    - If running on windows, _even if using wsl_, add the following entry to: `C:\Windows\System32\drivers\etc\hosts`
-      ```hosts
-      127.0.0.1 registry.wabbit-networks.io
-      ```
+  - If running on windows, _even if using wsl_, add the following entry to: `C:\Windows\System32\drivers\etc\hosts`
+
+    ```hosts
+    127.0.0.1 registry.wabbit-networks.io
+    ```
+
 - Continue with [Getting Started](#getting-started), but skip the environment variable configurations
 
 [notation-releases]:      https://github.com/shizhMSFT/notation/releases/tag/v0.5.0
 [artifact-manifest]:      https://github.com/oras-project/artifacts-spec/blob/main/artifact-manifest.md
-[cncf-distribution]:      https://github.com/oras-project/distribution
+[cncf-distribution]:      https://github.com/oras-project/distribution