From 4961cb0500fd3156e5c521b00b7bea8ef64f70a8 Mon Sep 17 00:00:00 2001 From: Kevin Paulisse Date: Thu, 11 Feb 2021 13:49:14 -0600 Subject: [PATCH] Fix indent and numbering in several docs --- doc/advanced-environments.md | 10 ++--- doc/advanced-puppet-master.md | 8 ++-- doc/configuration-puppet.md | 38 ++++++++--------- doc/configuration.md | 62 +++++++++++++-------------- doc/dev/integration-tests.md | 4 +- doc/dev/releasing.md | 80 +++++++++++++++++------------------ doc/dev/run-from-branch.md | 46 ++++++++++---------- doc/installation.md | 28 ++++++------ 8 files changed, 138 insertions(+), 138 deletions(-) diff --git a/doc/advanced-environments.md b/doc/advanced-environments.md index c17ebfb9..3b8098ac 100644 --- a/doc/advanced-environments.md +++ b/doc/advanced-environments.md @@ -15,13 +15,13 @@ If you are using environment names to control the behavior of Puppet, this defau When you supply the command line argument `--preserve-environments` (or set `settings[:preserve_environments] = true` in your [configuration file](/doc/configuration.md)), `octocatalog-diff` will instead do the following: 1. Create a temporary directory -2. Create the following symlinks from `` to the corresponding directories in the checkout of your code: +1. Create the following symlinks from `` to the corresponding directories in the checkout of your code: - - `environments` - - `manifests` - - `modules` + - `environments` + - `manifests` + - `modules` -3. Run Puppet using an environment you specify via the command line +1. Run Puppet using an environment you specify via the command line Note that you must have set `--preserve-environments` in order for the `--environment` and/or `--create-symlinks` options (described below) to have any effect. diff --git a/doc/advanced-puppet-master.md b/doc/advanced-puppet-master.md index eb52484b..d2c76b24 100644 --- a/doc/advanced-puppet-master.md +++ b/doc/advanced-puppet-master.md @@ -4,15 +4,15 @@ Please note the following caveats: -0. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously). +1. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously). -0. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you. +1. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you. -0. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use +1. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use the Puppet Master v4 API you may also use a Puppet Enterprise RBAC token. The user owning the token will need the "Puppet Server Compile catalogs for remote nodes" permission. See the [PE RBAC Token Authorization](#pe-rbac-token-authorization) section below. -0. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects. +1. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects. ## Command line options diff --git a/doc/configuration-puppet.md b/doc/configuration-puppet.md index 35217a2e..bf22f272 100644 --- a/doc/configuration-puppet.md +++ b/doc/configuration-puppet.md @@ -4,33 +4,33 @@ The most common use of `octocatalog-diff` is to use `puppet` locally to compile In order to successfully use Puppet to compile catalogs: -0. Puppet must be installed on the system. +1. Puppet must be installed on the system. - It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem. + It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem. - By default, `octocatalog-diff` will look for the Puppet binary in several common system locations. + By default, `octocatalog-diff` will look for the Puppet binary in several common system locations. - For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example: + For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example: - ``` - ############################################################################################## - # puppet_binary - # This is the full path to the puppet binary on your system. If you don't specify this, - # the tool will just run 'puppet' and hope to find it in your path. - ############################################################################################## + ``` + ############################################################################################## + # puppet_binary + # This is the full path to the puppet binary on your system. If you don't specify this, + # the tool will just run 'puppet' and hope to find it in your path. + ############################################################################################## - # settings[:puppet_binary] = '/usr/bin/puppet' - settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet' - ``` + # settings[:puppet_binary] = '/usr/bin/puppet' + settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet' + ``` -0. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled): +1. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled): - Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package. + Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package. - Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem. + Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem. - :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states: + :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states: - > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure. + > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure. - Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation. + Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation. diff --git a/doc/configuration.md b/doc/configuration.md index 775bbf8d..22a651d0 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -2,51 +2,51 @@ `octocatalog-diff` may require configuration to work correctly with your Puppet setup. -0. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories. +1. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories. - - In the base directory of your Puppet repository checkout (i.e., your current working directory): + - In the base directory of your Puppet repository checkout (i.e., your current working directory): - ``` - .octocatalog-diff.cfg.rb - ``` + ``` + .octocatalog-diff.cfg.rb + ``` - - In your home directory: + - In your home directory: - ``` - $HOME/.octocatalog-diff.cfg.rb - ``` + ``` + $HOME/.octocatalog-diff.cfg.rb + ``` - - In one of the following system locations: + - In one of the following system locations: - ``` - /usr/local/etc/octocatalog-diff.cfg.rb - /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb - /etc/octocatalog-diff.cfg.rb - ``` + ``` + /usr/local/etc/octocatalog-diff.cfg.rb + /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb + /etc/octocatalog-diff.cfg.rb + ``` - Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish. + Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish. -0. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration. +1. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration. - To be minimally functional, you will almost certainly need to define at least the following settings: + To be minimally functional, you will almost certainly need to define at least the following settings: - - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file - - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file - - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained + - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file + - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file + - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained - For more information on these settings: + For more information on these settings: - - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md) - - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md) - - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md) - - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md) + - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md) + - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md) + - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md) + - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md) -0. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof. +1. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof. - ``` - octocatalog-diff --config-test - ``` + ``` + octocatalog-diff --config-test + ``` - Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed. + Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed. Now that you have entered your configuration and confirmed proper reading of your configuration file, proceed to [Basic usage](/doc/basic.md) to see if it works! diff --git a/doc/dev/integration-tests.md b/doc/dev/integration-tests.md index 8bc0ae32..94050733 100644 --- a/doc/dev/integration-tests.md +++ b/doc/dev/integration-tests.md @@ -58,6 +58,6 @@ end ## Hints for writing an integration test -0. If your integration test deals only with the calculation or display of differences, and not catalog compilation, and you are compiling catalogs multiple times, prefer `spec_catalog_old` and `spec_catalog_new` to pass in pre-compiled catalogs. This will make the test run faster. +1. If your integration test deals only with the calculation or display of differences, and not catalog compilation, and you are compiling catalogs multiple times, prefer `spec_catalog_old` and `spec_catalog_new` to pass in pre-compiled catalogs. This will make the test run faster. -0. It's a good idea to check the exit code in a test of its own, and then `pending` any subsequent tests if that exit code doesn't match. This way only one test, and not all the tests, will fail if the catalog compilation doesn't work. +1. It's a good idea to check the exit code in a test of its own, and then `pending` any subsequent tests if that exit code doesn't match. This way only one test, and not all the tests, will fail if the catalog compilation doesn't work. diff --git a/doc/dev/releasing.md b/doc/dev/releasing.md index 45089e80..557b21c1 100644 --- a/doc/dev/releasing.md +++ b/doc/dev/releasing.md @@ -18,65 +18,65 @@ To test the new version of `octocatalog-diff` in the GitHub Puppet repository, c This section is useful when releasing a new version based on one PR submitted by a contributor. Following this workflow is important so that the contributor gets appropriate credit in the revision history for his or her work. -0. In your local checkout, start a new branch based off master. -0. Add the contributor's repository as a remote. For example: +1. In your local checkout, start a new branch based off master. +1. Add the contributor's repository as a remote. For example: - ``` - git remote add octocat https://github.com/octocat/octocatalog-diff.git - ``` + ``` + git remote add octocat https://github.com/octocat/octocatalog-diff.git + ``` -0. Merge in the contributor's branch into your own. For example: +1. Merge in the contributor's branch into your own. For example: - ``` - git merge octocat/some-branch - ``` + ``` + git merge octocat/some-branch + ``` -0. Update `.version` and `doc/CHANGELOG.md` appropriately. In CHANGELOG you should link to the PR submitted by the contributor (not the PR you're creating now). -0. Commit your changes to `.version` and `doc/CHANGELOG.md`. -0. If necessary, auto-generate the build documentation, and commit the changes to your branch. +1. Update `.version` and `doc/CHANGELOG.md` appropriately. In CHANGELOG you should link to the PR submitted by the contributor (not the PR you're creating now). +1. Commit your changes to `.version` and `doc/CHANGELOG.md`. +1. If necessary, auto-generate the build documentation, and commit the changes to your branch. - ``` - rake doc:build - ``` + ``` + rake doc:build + ``` -0. Open a Pull Request based on your branch. Confirm that the history is correct, showing the contributor's commits first, and then your commit(s) updating the version file, change log, and/or auto-generated documentation. -0. Ensure that CI tests are all passing. -0. Ensure that you've performed "local testing" within GitHub (typically, ~1 day) to confirm the changes. -0. Merge your PR and delete your branch. -0. Confirm that the contributor's PR now appears as merged, and any associated issues have been closed. +1. Open a Pull Request based on your branch. Confirm that the history is correct, showing the contributor's commits first, and then your commit(s) updating the version file, change log, and/or auto-generated documentation. +1. Ensure that CI tests are all passing. +1. Ensure that you've performed "local testing" within GitHub (typically, ~1 day) to confirm the changes. +1. Merge your PR and delete your branch. +1. Confirm that the contributor's PR now appears as merged, and any associated issues have been closed. ## Merging multiple PRs If multiple PRs will constitute a release, it's generally easier to merge each such PR individually, and then create a separate PR afterwards to update the necessary files. -0. Merge all constituent PRs and ensure that any associated issues have been closed. -0. Create your own branch based off master. -0. Update `.version` and `doc/CHANGELOG.md` appropriately. In CHANGELOG you should link to the PR submitted by the contributor (not the PR you're creating now). -0. Commit your changes to `.version` and `doc/CHANGELOG.md`. -0. If necessary, auto-generate the build documentation, and commit the changes to your branch. +1. Merge all constituent PRs and ensure that any associated issues have been closed. +1. Create your own branch based off master. +1. Update `.version` and `doc/CHANGELOG.md` appropriately. In CHANGELOG you should link to the PR submitted by the contributor (not the PR you're creating now). +1. Commit your changes to `.version` and `doc/CHANGELOG.md`. +1. If necessary, auto-generate the build documentation, and commit the changes to your branch. - ``` - rake doc:build - ``` + ``` + rake doc:build + ``` -0. Open a Pull Request based on your branch. -0. Ensure that CI tests are all passing. -0. Ensure that you've performed "local testing" within GitHub (typically, ~1 day) to confirm the changes. -0. Merge your PR and delete your branch. +1. Open a Pull Request based on your branch. +1. Ensure that CI tests are all passing. +1. Ensure that you've performed "local testing" within GitHub (typically, ~1 day) to confirm the changes. +1. Merge your PR and delete your branch. ## Releasing Generally, a new release will correspond to a merge to master of one or more Pull Requests. -0. Ensure that all changes associated with the release have been merged to master. - - Merge all Pull Requests associated with release, including the version number bump, change log update, etc. - - If necessary (for significant changes), complete a Pull Request to update the top-level README file. -0. Ensure the the master branch is checked out on your system. -0. Run the release procedure: +1. Ensure that all changes associated with the release have been merged to master. + - Merge all Pull Requests associated with release, including the version number bump, change log update, etc. + - If necessary (for significant changes), complete a Pull Request to update the top-level README file. +1. Ensure the the master branch is checked out on your system. +1. Run the release procedure: - ``` - rake gem:release - ``` + ``` + rake gem:release + ``` This rake task handles the following: diff --git a/doc/dev/run-from-branch.md b/doc/dev/run-from-branch.md index 6717b457..94e2cc27 100644 --- a/doc/dev/run-from-branch.md +++ b/doc/dev/run-from-branch.md @@ -8,38 +8,38 @@ This document is intended for people who may not be familiar with git, GitHub, a 1. Determine the branch name. If there's an open Pull Request, you can see the branch name near the top of the page. - ![Pull Request branch](/doc/images/pull-request-identify-branch.png) + ![Pull Request branch](/doc/images/pull-request-identify-branch.png) -2. Clone the `octocatalog-diff` repository in your home directory. From the command line: +1. Clone the `octocatalog-diff` repository in your home directory. From the command line: - ``` - cd $HOME - git clone https://github.com/github/octocatalog-diff.git - ``` + ``` + cd $HOME + git clone https://github.com/github/octocatalog-diff.git + ``` -3. Change into the directory created by your checkout: +1. Change into the directory created by your checkout: - ``` - cd $HOME/octocatalog-diff - ``` + ``` + cd $HOME/octocatalog-diff + ``` -4. Check out the branch you wish to use, filling in the branch name you determined in the first step: +1. Check out the branch you wish to use, filling in the branch name you determined in the first step: - ``` - git checkout BRANCH_NAME_FROM_STEP_1 - ``` + ``` + git checkout BRANCH_NAME_FROM_STEP_1 + ``` -5. Bootstrap the repository to pull in dependencies: +1. Bootstrap the repository to pull in dependencies: - ``` - ./script/bootstrap - ``` + ``` + ./script/bootstrap + ``` -6. Optional but recommended - run the test suite: +1. Optional but recommended - run the test suite: - ``` - rake - ``` + ``` + rake + ``` ## Use @@ -53,7 +53,7 @@ We've created a wrapper script to make this easier for you. cd /etc/puppetlabs/code ``` -2. Run the `script/octocatalog-diff-wrapper` script from *this* checkout. For example, if you checked out `octocatalog-diff` to your home directory, you could use: +1. Run the `script/octocatalog-diff-wrapper` script from *this* checkout. For example, if you checked out `octocatalog-diff` to your home directory, you could use: ``` $HOME/octocatalog-diff/script/octocatalog-diff-wrapper diff --git a/doc/installation.md b/doc/installation.md index d5fa1036..891529ee 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -25,26 +25,26 @@ For general information on installing gems, see: [RubyGems Basics](http://guides To install from source, you'll need a git client and internet access. -0. Clone the repository +1. Clone the repository - ``` - git clone https://github.com/github/octocatalog-diff.git - ``` + ``` + git clone https://github.com/github/octocatalog-diff.git + ``` -0. Bootstrap the repository (this will install dependent gems in the project) +1. Bootstrap the repository (this will install dependent gems in the project) - ``` - cd octocatalog-diff - ./script/bootstrap - ``` + ``` + cd octocatalog-diff + ./script/bootstrap + ``` -0. RECOMMENDED: Make sure the tests pass on your machine +1. RECOMMENDED: Make sure the tests pass on your machine - ``` - rake - ``` + ``` + rake + ``` - Note: If tests fail on your machine with a clean checkout of the master branch, we would definitely appreciate if you would report it. Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) with the output and some information about your system (e.g. OS, ruby version, etc.) to let us know. + Note: If tests fail on your machine with a clean checkout of the master branch, we would definitely appreciate if you would report it. Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) with the output and some information about your system (e.g. OS, ruby version, etc.) to let us know. Once the code is downloaded and bootstrapped, please proceed to [Configuration](/doc/configuration.md).